event

Documentation

Overview

Package event provides structures to propagate event occurrences to subscribed system entities.

Index

• Variables
• func EnterLoop(bus Handler, frameDelay time.Duration) (cancel func())
• func TriggerForCallerOn[T any](b Handler, cid CallerID, ev EventID[T], data T) <-chan struct{}
• func TriggerOn[T any](b Handler, ev EventID[T], data T) <-chan struct{}
• type BindID
• type Bindable
• type Binding
  • func Bind[C Caller, Payload any](h Handler, ev EventID[Payload], caller C, fn Bindable[C, Payload]) Binding
  • func GlobalBind[Payload any](h Handler, ev EventID[Payload], fn GlobalBindable[Payload]) Binding
  • func (b Binding) Unbind() <-chan struct{}
• type Bus
  • func NewBus(callerMap *CallerMap) *Bus
  • func (eb *Bus) ClearPersistentBindings()
  • func (b *Bus) GetCallerMap() *CallerMap
  • func (bus *Bus) PersistentBind(eventID UnsafeEventID, callerID CallerID, fn UnsafeBindable) Binding
  • func (bus *Bus) Reset()
  • func (bus *Bus) SetCallerMap(cm *CallerMap)
  • func (bus *Bus) Trigger(eventID UnsafeEventID, data interface{}) <-chan struct{}
  • func (bus *Bus) TriggerForCaller(callerID CallerID, eventID UnsafeEventID, data interface{}) <-chan struct{}
  • func (bus *Bus) Unbind(loc Binding) <-chan struct{}
  • func (bus *Bus) UnbindAllFrom(c CallerID) <-chan struct{}
  • func (bus *Bus) UnsafeBind(eventID UnsafeEventID, callerID CallerID, fn UnsafeBindable) Binding
• type Caller
• type CallerID
  • func (c CallerID) CID() CallerID
• type CallerMap
  • func NewCallerMap() *CallerMap
  • func (cm *CallerMap) Clear()
  • func (cm *CallerMap) GetEntity(id CallerID) Caller
  • func (cm *CallerMap) HasEntity(id CallerID) bool
  • func (cm *CallerMap) Register(e Caller) CallerID
  • func (cm *CallerMap) RemoveEntity(id CallerID)
• type EnterPayload
• type EventID
  • func RegisterEvent[T any]() EventID[T]
• type GlobalBindable
• type Handler
• type Response
• type UnsafeBindable
• type UnsafeEventID

Variables

var (
	// Enter: the beginning of every logical frame.
	Enter = RegisterEvent[EnterPayload]()
)

Functions

func EnterLoop

func EnterLoop(bus Handler, frameDelay time.Duration) (cancel func())

EnterLoop triggers Enter events at the specified rate until the returned cancel is called.

func TriggerForCallerOn

func TriggerForCallerOn[T any](b Handler, cid CallerID, ev EventID[T], data T) <-chan struct{}

TriggerForCallerOn calls TriggerForCaller with a strongly typed event.

func TriggerOn

func TriggerOn[T any](b Handler, ev EventID[T], data T) <-chan struct{}

TriggerOn calls Trigger with a strongly typed event.

Types

type BindID

type BindID int64

A BindID is a unique identifier for a binding within a bus.

type Bindable

type Bindable[C any, Payload any] func(C, Payload) Response

A Bindable is a strongly typed callback function to be executed on Trigger. It must be paired with an event registered via RegisterEvent.

type Binding

type Binding struct {
	Handler  Handler
	EventID  UnsafeEventID
	CallerID CallerID
	BindID   BindID

	// Bound is closed once the binding has been applied. Wait on this condition carefully; bindings
	// will not take effect while an event is being triggered (e.g. in a event callback's returning thread)
	Bound <-chan struct{}
	// contains filtered or unexported fields
}

A Binding, returned from calls to Bind, references the details of a binding and where that binding is stored within a handler. The common use case for this structure would involve a system that wanted to keep track of its bindings for later remote unbinding. This structure can also be used to construct and unbind a known reference.

func Bind

func Bind[C Caller, Payload any](h Handler, ev EventID[Payload], caller C, fn Bindable[C, Payload]) Binding

Bind will cause the function fn to be called whenever the event ev is triggered on the given event handler. The function will be called with the provided caller as its first argument, and will also be called when the provided event is specifically triggered on the caller's ID.

func GlobalBind

func GlobalBind[Payload any](h Handler, ev EventID[Payload], fn GlobalBindable[Payload]) Binding

GlobalBind will cause the function fn to be called whenever the event ev is triggered on the given event handler.

func (Binding) Unbind

func (b Binding) Unbind() <-chan struct{}

Unbind unbinds the callback associated with this binding from it's own event handler. If this binding does not belong to its handler or has already been unbound, this will do nothing.

type Bus

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

A Bus stores bindables to be triggered by events.

var DefaultBus *Bus

DefaultBus is a global Bus. It uses the DefaultCallerMap internally. It should not be used unless your program is only using a single Bus. Preferably multi-bus programs would create their own buses and caller maps specific to each bus's use.

func NewBus

func NewBus(callerMap *CallerMap) *Bus

NewBus returns an empty event bus with an assigned caller map. If nil is provided, the caller map used will be DefaultCallerMap

func (*Bus) ClearPersistentBindings

func (eb *Bus) ClearPersistentBindings()

ClearPersistentBindings removes all persistent bindings. It will not unbind them from the bus, but they will not be bound following the next bus reset.

func (*Bus) GetCallerMap

func (b *Bus) GetCallerMap() *CallerMap

GetCallerMap returns this bus's caller map.

func (*Bus) PersistentBind

func (bus *Bus) PersistentBind(eventID UnsafeEventID, callerID CallerID, fn UnsafeBindable) Binding

PersistentBind calls UnsafeBind, and causes UnsafeBind to be called with these inputs when a Bus is Reset, i.e. persisting the binding through bus resets. Unbinding this will not stop it from being rebound on the next Bus Reset-- ClearPersistentBindings will. If called concurrently during a bus Reset, the request may not be bound until the next bus Reset.

func (*Bus) Reset

func (bus *Bus) Reset()

Reset unbinds all present, non-persistent bindings on the bus. It will block until persistent bindings are in place.

func (*Bus) SetCallerMap

func (bus *Bus) SetCallerMap(cm *CallerMap)

SetCallerMap updates a bus to use a specific set of callers.

func (*Bus) Trigger

func (bus *Bus) Trigger(eventID UnsafeEventID, data interface{}) <-chan struct{}

Trigger will scan through the event bus and call all bindables found attached to the given event, with the passed in data.

func (*Bus) TriggerForCaller

func (bus *Bus) TriggerForCaller(callerID CallerID, eventID UnsafeEventID, data interface{}) <-chan struct{}

TriggerForCaller acts like Trigger, but will only trigger for the given caller.

func (*Bus) Unbind

func (bus *Bus) Unbind(loc Binding) <-chan struct{}

Unbind unregisters a binding from a bus concurrently. Once complete, triggers that would have previously caused the Bindable callback to execute will no longer do so.

func (*Bus) UnbindAllFrom

func (bus *Bus) UnbindAllFrom(c CallerID) <-chan struct{}

UnbindAllFrom unbinds all bindings currently bound to the provided caller via ID.

func (*Bus) UnsafeBind

func (bus *Bus) UnsafeBind(eventID UnsafeEventID, callerID CallerID, fn UnsafeBindable) Binding

UnsafeBind registers a callback function to be called whenever the provided event is triggered against this bus. The binding is concurrently bound, and therefore may not be immediately available to be triggered. When Reset is called on a Bus, all prior bindings are unbound and any concurrent calls to UnsafeBind will not take effect. This call is 'unsafe' because UnsafeBindables use bare interface{} types.

type Caller

type Caller interface {
	CID() CallerID
}

type CallerID

type CallerID int64

A CallerID is a caller ID that Callers use to bind themselves to receive callback signals when given events are triggered

const Global CallerID = 0

Global is the CallerID associated with global bindings. A caller must not be assigned this ID. Global may be used to manually create bindings scoped to no callers, but the GlobalBind function should be preferred when possible for type safety.

func (CallerID) CID

func (c CallerID) CID() CallerID

type CallerMap

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

A CallerMap tracks CallerID mappings to Entities. This is an alternative to passing in the entity via closure scoping, and allows for more general bindings as simple top level functions.

var DefaultCallerMap *CallerMap

DefaultCallerMap is a global CallerMap. It should not be used unless your program is only using a single CallerMap, or in other words definitely only has one event bus running at a time.

func NewCallerMap

func NewCallerMap() *CallerMap

NewCallerMap creates a caller map. A CallerMap is not valid for use if not created via this function.

func (*CallerMap) Clear

func (cm *CallerMap) Clear()

Clear clears the caller map to forget all registered callers.

func (*CallerMap) GetEntity

func (cm *CallerMap) GetEntity(id CallerID) Caller

Get returns the entity corresponding to the given ID within the caller map. If no entity is found, it returns nil.

func (*CallerMap) HasEntity

func (cm *CallerMap) HasEntity(id CallerID) bool

Has returns whether the given caller id is an initialized entity within the caller map.

func (*CallerMap) Register

func (cm *CallerMap) Register(e Caller) CallerID

NextID finds the next available caller id and returns it, after adding the given entity to the caller map.

func (*CallerMap) RemoveEntity

func (cm *CallerMap) RemoveEntity(id CallerID)

Remove removes an entity from the caller map.

type EnterPayload

type EnterPayload struct {
	FramesElapsed  int
	SinceLastFrame time.Duration
	TickPercent    float64
}

EnterPayload is the payload sent down to Enter bindings

type EventID

type EventID[T any] struct {
	UnsafeEventID
}

A EventID represents an event associated with a given payload type.

func RegisterEvent

func RegisterEvent[T any]() EventID[T]

RegisterEvent returns a unique ID to associate an event with. EventIDs not created through RegisterEvent are not valid for use in type-safe bindings.

type GlobalBindable

type GlobalBindable[Payload any] func(Payload) Response

A GlobalBindable is a bindable that is not bound to a specific caller.

type Handler

type Handler interface {
	Reset()
	TriggerForCaller(cid CallerID, event UnsafeEventID, data interface{}) <-chan struct{}
	Trigger(event UnsafeEventID, data interface{}) <-chan struct{}
	UnsafeBind(UnsafeEventID, CallerID, UnsafeBindable) Binding
	Unbind(Binding) <-chan struct{}
	UnbindAllFrom(CallerID) <-chan struct{}
	SetCallerMap(*CallerMap)
	GetCallerMap() *CallerMap
	PersistentBind(eventID UnsafeEventID, callerID CallerID, fn UnsafeBindable) Binding
	ClearPersistentBindings()
}

Handler represents the necessary exported functions from an event.Bus for use in oak internally, and thus the functions that need to be replaced by alternative event handlers.

type Response

type Response uint8

const (
	// ResponseNone or 0, is returned by events that
	// don't want the event bus to do anything with
	// the event after they have been evaluated. This
	// is the usual behavior.
	ResponseNone Response = iota
	// ResponseUnbindThisBinding unbinds the one binding that returns it.
	ResponseUnbindThisBinding
	// ResponseUnbindThisCaller unbinds all of a caller's bindings when returned from any binding.
	ResponseUnbindThisCaller
)

Response types for bindables

type UnsafeBindable

type UnsafeBindable func(CallerID, Handler, interface{}) Response

UnsafeBindable defines the underlying signature of all bindings.

type UnsafeEventID

type UnsafeEventID int64

An UnsafeEventID is a non-typed eventID. EventIDs are just these, with type information attached.