goalstate

Documentation

Overview

Package goalstate implements a engine to drive a goal state machine. Any item enqueued into the goal state engine needs to implement the Entity interface. The enqueued entity should be able to fetch a unique string identifier, its state and goal state, and should be able to fetch an action list for a given state and goal state. Each action should implement the action function interface. The engine provides an Enqueue function which can be used to enqueue an entity with a deadline of when it is should be dequeued for evaluation. When its deadline expires, the action list corresponding to its state and goal state are executed in order. If any of the actions return an error on execution, the entity is requeued for evaluation with an exponential backoff.

Index

• type Action
• type ActionExecute
• type Engine
  • func NewEngine(numWorkerThreads int, failureRetryDelay time.Duration, ...) Engine
• type Entity
• type Metrics
  • func NewMetrics(scope tally.Scope) *Metrics

Types

type Action

type Action struct {
	// Name of the action which will be used as the tag in the emitted metrics.
	Name string
	// Execute is the function called by the goal state
	// engine to execute the action.
	Execute ActionExecute
}

Action defines the interface for the function to be used by goal state actions. If the Execute call returns an error, the entity is rescheduled in the goal state engine with an exponential backoff.

type ActionExecute

type ActionExecute func(ctx context.Context, entity Entity) error

ActionExecute defines the interface for the function to be used by the goal state engine clients to implement the execution of an action.

type Engine

type Engine interface {
	// Start starts the goal state engine processing.
	Start()
	// Enqueue is used to enqueue an entity into the goal state
	// engine for evaluation. The paramater deadline specifies when
	// the entity should be evaluated.
	// Enqueue creates state in the goal state engine which will persist
	// till the caller calls an explicit delete to clean up this state.
	Enqueue(entity Entity, deadline time.Time)
	// IsScheduled is used to determine if a given entity is queued in
	// the deadline queue for evaluation
	IsScheduled(entity Entity) bool
	// Delete is used clean up the state created in the goal state
	// engine for the entity. It is the caller's responsibility to
	// explicitly call delete when an entity is being removed from the system.
	// If Delete is not called, the state in goal state engine will persis forever.
	Delete(entity Entity)
	// Stops stops the goal state engine processing.
	Stop()
}

Engine defines the goal state engine interface.

func NewEngine

func NewEngine(
	numWorkerThreads int,
	failureRetryDelay time.Duration,
	maxRetryDelay time.Duration,
	parentScope tally.Scope) Engine

NewEngine returns a new goal state engine object.

type Entity

type Entity interface {
	// GetID fetches the identifier of the entity.
	GetID() string
	// GetState fetches the current state of the entity.
	GetState() interface{}
	// GetGoalState fetches the current goal state of the entity.
	GetGoalState() interface{}
	// GetActionList fetches the set of actions which need to be executed
	// for the entity's current state and goal state.
	// The action list is an array of actions which are executed in order.
	// Each action needs to be idempotent.
	GetActionList(state interface{}, goalState interface{}) (
		context.Context, context.CancelFunc, []Action)
}

Entity defines the interface of an item which can queued into the goal state engine.

type Metrics

type Metrics struct {
	// contains filtered or unexported fields
}

Metrics contains counters to track goal state engine metrics

func NewMetrics

func NewMetrics(scope tally.Scope) *Metrics

NewMetrics returns a new Metrics struct.