dsl

Documentation

Index

• func EmitEvent(m Module, ev *eventpb.Event)
• func EmitMirEvent(m Module, ev *eventpbtypes.Event)
• func MirOrigin(contextID ContextID) *dslpbtypes.Origin
• func Origin(contextID ContextID) *dslpbtypes.Origin
• func UponEvent[EvWrapper eventpb.Event_TypeWrapper[Ev], Ev any](m Module, handler func(ev *Ev) error)
• func UponInit(m Module, handler func() error)
• func UponMirEvent[EvWrapper eventpbtypes.Event_TypeWrapper[Ev], Ev any](m Module, handler func(ev *Ev) error)
• func UponOtherEvent(m Module, handler func(ev *eventpb.Event) error)
• func UponStateUpdate(m Module, handler func() error)
• func UponStateUpdates(m Module, handler func() error)
• type ContextID
• type Handle
  • func (h Handle) CleanupContext(id ContextID)
  • func (h Handle) RecoverAndCleanupContext(id ContextID) any
  • func (h Handle) RecoverAndRetainContext(id cs.ItemID) any
  • func (h Handle) StoreContext(context any) ContextID
• type Module
  • func NewModule(moduleID t.ModuleID) Module

Functions

func EmitEvent

func EmitEvent(m Module, ev *eventpb.Event)

EmitEvent adds the event to the queue of output events NB: This function works with the (legacy) protoc-generated types and is likely to be removed in the future, with EmitMirEvent taking its place.

func EmitMirEvent

func EmitMirEvent(m Module, ev *eventpbtypes.Event)

EmitMirEvent adds the event to the queue of output events NB: this function works with the Mir-generated types. For the (legacy) protoc-generated types, EmitEvent can be used.

func MirOrigin

func MirOrigin(contextID ContextID) *dslpbtypes.Origin

MirOrigin creates a dslpb.Origin protobuf.

func Origin

func Origin(contextID ContextID) *dslpbtypes.Origin

Origin creates a dslpb.Origin protobuf.

func UponEvent

func UponEvent[EvWrapper eventpb.Event_TypeWrapper[Ev], Ev any](m Module, handler func(ev *Ev) error)

UponEvent registers an event handler for module m. This event handler will be called every time an event of type EvWrapper is received. NB: This function works with the (legacy) protoc-generated types and is likely to be removed in the future, with UponMirEvent taking its place.

func UponInit

func UponInit(m Module, handler func() error)

UponInit invokes handler when the module is initialized.

func UponMirEvent

func UponMirEvent[EvWrapper eventpbtypes.Event_TypeWrapper[Ev], Ev any](m Module, handler func(ev *Ev) error)

UponMirEvent registers an event handler for module m. This event handler will be called every time an event of type EvWrapper is received. NB: this function works with the Mir-generated types. For the (legacy) protoc-generated types, UponEvent can be used.

func UponOtherEvent

func UponOtherEvent(m Module, handler func(ev *eventpb.Event) error)

func UponStateUpdate

func UponStateUpdate(m Module, handler func() error)

UponStateUpdate registers a special type of handler that is invoked after the processing of every event. The handler is intended to represent a conditional action: it is supposed to check some predicate on the state and perform actions if the predicate is satisfied. This is, however, not enforced in any way, and the handler can contain arbitrary code. Use with care, especially if the execution overhead of the handler is not negligible. Execution of these handlers might easily have a severe impact on performance.

func UponStateUpdates

func UponStateUpdates(m Module, handler func() error)

UponStateUpdates registers a special type of handler that is invoked each time after processing a batch of events. It is a less resource-intensive alternative to UponStateUpdate that is useful if intermediate states of the module are not relevant (as not all intermediate states of the module are observed by handlers registered using UponStateUpdates).

ATTENTION: The handler always called after applying a *batch of* events, not after individual event application. This can lead to unintuitive behavior. For example, a counter module maintaining an internal counter variable that is incremented on every event could register a state update handler checking for counter == 10. Due to (unpredictable) event application batching, the counter can go from 0 to 20 without having triggered the condition handler, if events 10 and 11 are applied in the same batch.

Types

type ContextID

type ContextID = cs.ItemID

ContextID is used to address the internal context store of the dsl module.

type Handle

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

Handle is used to manage internal state of the dsl module.

func (Handle) CleanupContext

func (h Handle) CleanupContext(id ContextID)

CleanupContext schedules a disposal of context with the given id after the current batch of events is processed. NB: the context cannot be disposed of immediately because there may be more event handlers for this event that may need this context.

func (Handle) RecoverAndCleanupContext

func (h Handle) RecoverAndCleanupContext(id ContextID) any

RecoverAndCleanupContext recovers the context with te given id and schedules a disposal of this context after the current batch of events is processed. NB: the context cannot be disposed of immediately because there may be more event handlers for this event that may need this context.

func (Handle) RecoverAndRetainContext

func (h Handle) RecoverAndRetainContext(id cs.ItemID) any

RecoverAndRetainContext recovers the context with the given id and retains it in the internal context store so that it can be recovered again later. Only use this function when expecting to receive multiple events with the same context. In case of a typical request-response semantic, use RecoverAndCleanupContext.

func (Handle) StoreContext

func (h Handle) StoreContext(context any) ContextID

StoreContext stores the given data and returns an automatically deterministically generated unique id. The data can be later recovered or disposed of using this id.

type Module

type Module interface {
	modules.PassiveModule

	// DslHandle is used to manage internal state of the dsl module.
	DslHandle() Handle

	// ModuleID returns the identifier of the module.
	// TODO: consider moving this method to modules.Module.
	ModuleID() t.ModuleID
}

Module allows creating passive modules in a very natural declarative way.

func NewModule

func NewModule(moduleID t.ModuleID) Module

NewModule creates a new dsl module with a given id.