Documentation ¶
Overview ¶
Tideland Cells is a framework for event and behavior based applications.
Cell behaviors are defined based on an interface and can be added to an envrionment. Here they are running as concurrent cells that can be networked and communicate via events. Several useful behaviors are provided with the behaviors package.
New environments are created with
env := cells.NewEnvironment(identifier)
and cells are added with
env.StartCell("foo", NewFooBehavior())
Cells then can be subscribed with
env.Subscribe("foo", "bar")
so that events emitted by the "foo" cell during the processing of events will be received by the "bar" cell. Each cell can have multiple cells subscibed.
Events from the outside are emitted using
env.Emit("foo", myEvent)
or
env.EmitNew("foo", "myTopic", cells.PayloadValues{ "KeyA": 12345, "KeyB": true, }, myScene)
Behaviors have to implement the cells.Behavior interface. Here the Init() method is called with a cells.Context. This can be used inside the ProcessEvent() method to emit events to subscribers or directly to other cells of the environment.
Sometimes it's needed to directly communicate with a cell to retrieve information. In this case the method
response, err := env.Request("foo", "myRequest?", myPayload, myScene, myTimeout)
is to be used. Inside the ProcessEvent() of the addressed cell the event can be used to send the response with
switch event.Topic() { case "myRequest?": event.Respond(someIncredibleData) case ...: ... }
Instructions without a response are simply done by emitting an event.
Index ¶
- Constants
- func IsCannotRecoverError(err error) bool
- func IsCellInitError(err error) bool
- func IsDuplicateIDError(err error) bool
- func IsEventRecoveringError(err error) bool
- func IsInactiveError(err error) bool
- func IsInvalidIDError(err error) bool
- func IsInvalidResponseError(err error) bool
- func IsInvalidResponseEventError(err error) bool
- func IsMissingSceneError(err error) bool
- func IsNoRequestError(err error) bool
- func IsNoTopicError(err error) bool
- func IsRecoveredTooOftenError(err error) bool
- func IsStoppingError(err error) bool
- func IsTimeoutError(err error) bool
- func NewCannotRecoverError(id string, err interface{}) error
- func NewInvalidResponseError(response interface{}) error
- func PackageVersion() version.Version
- type Behavior
- type BehaviorEmitTimeout
- type BehaviorEventBufferSize
- type BehaviorRecoveringFrequency
- type Context
- type Environment
- type Event
- type Payload
- type PayloadValues
- type Subscriber
Constants ¶
const ( // Often used standard topics. CollectedTopic = "collected?" CountersTopic = "counters?" PingTopic = "ping?" ProcessedTopic = "processed?" ResetTopic = "reset!" StatusTopic = "status?" TickTopic = "tick!" // Standard payload keys. DefaultPayload = "default" ResponseChanPayload = "responseChan" TickerIDPayload = "ticker:id" TickerTimePayload = "ticker:time" // Special responses. PongResponse = "pong!" // Default timeout for requests to cells. DefaultTimeout = 5 * time.Second )
const ( ErrCellInit = iota + 1 ErrCannotRecover ErrDuplicateID ErrInvalidID ErrExecuteID ErrEventRecovering ErrRecoveredTooOften ErrNoTopic ErrNoRequest ErrInactive ErrStopping ErrTimeout ErrMissingScene ErrInvalidResponseEvent ErrInvalidResponse )
Variables ¶
This section is empty.
Functions ¶
func IsCannotRecoverError ¶
IsCannotRecoverError checks if an error shows a cell that cannot recover.
func IsCellInitError ¶
IsCellInitError checks if an error is a cell init error.
func IsDuplicateIDError ¶
IsDuplicateIDError checks if an error is a cell already exists error.
func IsEventRecoveringError ¶
IsEventRecoveringError checks if an error is an error recovering error.
func IsInactiveError ¶
IsInactiveError checks if an error is a cell inactive error.
func IsInvalidIDError ¶
IsInvalidIDError checks if an error is a cell does not exist error.
func IsInvalidResponseError ¶
IsInvalidResponseError checks if an error signals an invalid response.
func IsInvalidResponseEventError ¶
IsInvalidResponseEventError checks if an error signals an event used for a response but containing no storeID as payload and/or no scene.
func IsMissingSceneError ¶
IsMissingSceneError checks if an error signals a request without a scene.
func IsNoRequestError ¶
IsNoRequestError checks if an error signals that an event is no request.
func IsNoTopicError ¶
IsNoTopicError checks if an error shows that an event has no topic..
func IsRecoveredTooOftenError ¶
IsRecoveredTooOftenError checks if an error is an illegal query error.
func IsStoppingError ¶
IsStoppingError checks if the error shows a stopping entity.
func IsTimeoutError ¶
IsTimeoutError checks if an error is a timeout error.
func NewCannotRecoverError ¶
NewCannotRecoverError returns an error showing that a cell cannot recover from errors.
func NewInvalidResponseError ¶
func NewInvalidResponseError(response interface{}) error
NewInvalidResponseError returns an error showing that a response to a request has an illegal type.
func PackageVersion ¶
PackageVersion returns the version of the version package.
Types ¶
type Behavior ¶
type Behavior interface { // Init is called to initialize the behavior inside the environment. // The passed context allows the behavior to interact with this // environment and to emit events to subscribers during ProcessEvent(). // So if this is needed the context should be stored inside the behavior. Init(ctx Context) error // Terminate is called when a cell is stopped. Terminate() error // ProcessEvent is called to process the passed event. If during this // processing one or more events shall be emitted to the subscribers // the context passed during Init() is needed. ProcessEvent(event Event) error // Recover is called in case of an error or panic during the processing // of an event. Here the behavior can check if it can recover and establish // a valid state. If it's not possible the implementation has to return // an error documenting the reason. Recover(r interface{}) error }
Behavior is the interface that has to be implemented for the usage inside of cells.
type BehaviorEmitTimeout ¶
BehaviorEmitTimeout is an additional optional interface for a behavior to set the maximum time an emitter is waiting for a receiving cell to accept the emitted event (will always between 5 and 30 seconds with a 5 seconds timing).
type BehaviorEventBufferSize ¶
type BehaviorEventBufferSize interface {
EventBufferSize() int
}
BehaviorEventBufferSize is an additional optional interface for a behavior to set the size of the event buffer (will never be below 16).
type BehaviorRecoveringFrequency ¶
BehaviorRecoveringFrequency is an additional optional interface for a behavior to set the allowed frequency for recoverings by returning the according number and duration (will never below once per second).
type Context ¶
type Context interface { // Environment returns the environment the cell is running in. Environment() Environment // ID returns the ID used during the start of the cell. The same cell // can be started multiple times but has to use different IDs. ID() string // Emit emits an event to all subscribers of a cell. Emit(event Event) error // EmitNew creates an event and emits it to all subscribers of a cell. EmitNew(topic string, payload interface{}, scene scene.Scene) error // SubscribersDo calls the passed function for each subscriber. SubscribersDo(f func(s Subscriber) error) error }
Context gives a behavior access to its environment.
type Environment ¶
type Environment interface { // ID returns the ID of the environment. When creating the environment // the ID can by set manually or is generated automatically. ID() string // StartCell starts a new cell with a given ID and its behavior. StartCell(id string, behavior Behavior) error // StopCell stops and removes the cell with the given ID. StopCell(id string) error // HasCell returns true if the cell with the given ID exists. HasCell(id string) bool // Subscribe assigns cells as receivers of the emitted // events of the first cell. Subscribe(emitterID string, subscriberIDs ...string) error // Subscribers returns the subscribers of the passed ID. Subscribers(id string) ([]string, error) // Unsubscribe removes the assignment of emitting und subscribed cells. Unsubscribe(emitterID string, unsubscriberIDs ...string) error // Emit emits an event to the cell with a given ID. Emit(id string, event Event) error // EmitNew creates an event and emits it to the cell with a given ID. EmitNew(id, topic string, payload interface{}, scn scene.Scene) error // Request creates and emits an event to the cell with the given ID. // It is intended as request which has to be responded to with // event.Respond(). Request(id, topic string, payload interface{}, scn scene.Scene, timeout time.Duration) (interface{}, error) // Stop manages the proper finalization of an environment. Stop() error }
Environment is a set of networked cells.
func NewEnvironment ¶
func NewEnvironment(idParts ...interface{}) Environment
NewEnvironment creates a new environment.
type Event ¶
type Event interface { fmt.Stringer // Topic returns the topic of the event. Topic() string // Payload returns the payload of the event. Payload() Payload // Scene returns a scene that is possibly emitted // with the event. Scene() scene.Scene // Respond responds to a request event emitted // with Environment.Request(). Respond(response interface{}) error }
Event transports what to process.
type Payload ¶
type Payload interface { fmt.Stringer // Len returns the number of values. Len() int // Get returns one of the payload values. Get(key string) (interface{}, bool) // GetBool returns one of the payload values // as bool. If it's no bool false is returned. GetBool(key string) (bool, bool) // GetInt returns one of the payload values // as int. If it's no int false is returned. GetInt(key string) (int, bool) // GetFloat64 returns one of the payload values // as float64. If it's no float64 false is returned. GetFloat64(key string) (float64, bool) // GetString returns one of the payload values // as string. If it's no string false is returned. GetString(key string) (string, bool) // GetTime returns one of the payload values // as time.Time. If it's no time false is returned. GetTime(key string) (time.Time, bool) // GetDuration returns one of the payload values as // time.Duration. If it's no duration false is returned. GetDuration(key string) (time.Duration, bool) // Keys return all keys of the payload. Keys() []string // Do iterates a function over all keys and values. Do(f func(key string, value interface{}) error) error // Apply creates a new payload containing the values // of this one and the passed values. Allowed are // PayloadValues, map[string]interface{}, and any // other single value. The latter will be stored // with the cells.DefaultPayload key. Values of this // payload are overwritten by those which are passed // if they share the key. Apply(values interface{}) Payload }
Payload is a write-once/read-multiple container for the transport of additional information with events. In case one item is a reference type it's in the responsibility of the users to avoid concurrent changes of their values.
func NewPayload ¶
func NewPayload(values interface{}) Payload
NewPayload creates a new payload containing the passed values. In case of a Payload this is used directly, in case of a PayloadValues or a map[string]interface{} their content is used, and when passing any other type the value is stored with the key cells.DefaultPayload.
type PayloadValues ¶
type PayloadValues map[string]interface{}
PayloadValues is intended to set and get the information of a payload as bulk.
type Subscriber ¶
type Subscriber interface { // ID returns the ID of the subscriber. ID() string // ProcessEvent tells the subscriber to process an event. ProcessEvent(event Event) error // ProcessNewEvent creates an event and tells the subscriber to process it. ProcessNewEvent(topic string, payload interface{}, scene scene.Scene) error }
Subscriber describes a subscriber cell for an emitting cell.