cells

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
  • func NewEnvironment(idParts ...interface{}) Environment
• type Event
  • func NewEvent(topic string, payload interface{}, scene scene.Scene) (Event, error)
• type Payload
  • func NewPayload(values interface{}) 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
)

Functions

func IsCannotRecoverError

func IsCannotRecoverError(err error) bool

IsCannotRecoverError checks if an error shows a cell that cannot recover.

func IsCellInitError

func IsCellInitError(err error) bool

IsCellInitError checks if an error is a cell init error.

func IsDuplicateIDError

func IsDuplicateIDError(err error) bool

IsDuplicateIDError checks if an error is a cell already exists error.

func IsEventRecoveringError

func IsEventRecoveringError(err error) bool

IsEventRecoveringError checks if an error is an error recovering error.

func IsInactiveError

func IsInactiveError(err error) bool

IsInactiveError checks if an error is a cell inactive error.

func IsInvalidIDError

func IsInvalidIDError(err error) bool

IsInvalidIDError checks if an error is a cell does not exist error.

func IsInvalidResponseError

func IsInvalidResponseError(err error) bool

IsInvalidResponseError checks if an error signals an invalid response.

func IsInvalidResponseEventError

func IsInvalidResponseEventError(err error) bool

IsInvalidResponseEventError checks if an error signals an event used for a response but containing no storeID as payload and/or no scene.

func IsMissingSceneError

func IsMissingSceneError(err error) bool

IsMissingSceneError checks if an error signals a request without a scene.

func IsNoRequestError

func IsNoRequestError(err error) bool

IsNoRequestError checks if an error signals that an event is no request.

func IsNoTopicError

func IsNoTopicError(err error) bool

IsNoTopicError checks if an error shows that an event has no topic..

func IsRecoveredTooOftenError

func IsRecoveredTooOftenError(err error) bool

IsRecoveredTooOftenError checks if an error is an illegal query error.

func IsStoppingError

func IsStoppingError(err error) bool

IsStoppingError checks if the error shows a stopping entity.

func IsTimeoutError

func IsTimeoutError(err error) bool

IsTimeoutError checks if an error is a timeout error.

func NewCannotRecoverError

func NewCannotRecoverError(id string, err interface{}) error

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

func PackageVersion() version.Version

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

type BehaviorEmitTimeout interface {
	EmitTimeout() time.Duration
}

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

type BehaviorRecoveringFrequency interface {
	RecoveringFrequency() (int, time.Duration)
}

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.

func NewEvent

func NewEvent(topic string, payload interface{}, scene scene.Scene) (Event, error)

NewEvent creates a new event with the given topic and payload.

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.