nupp.events

events.newMessageBusconstructor#

function events.newMessageBus<A>(): events.MessageBus<A>

A bus with no observers.

The address type is whatever the binding asks for: local bus: events.MessageBus<integer> = events.newMessageBus().

Type parameters

Returns

events.newObserversconstructor#

function events.newObservers<A>(): events.Observers<A>

Empty observer state for a new source.

Type parameters

Returns

Allocatorinterface#

interface events.Allocator<E>
    acquire: function(exclusive self: Allocator<E>): E
    release: function(exclusive self: Allocator<E>, value: E): nil
end

Storage an event type is constructed into and returned to.

acquire hands out reusable storage of the event's own representation, which the emitting source initializes; release ends that lease when delivery is over. nupp.mem.pool and nupp.mem.arena implement it.

Type parameters

Methods

acquire: function(exclusive self: Allocator<E>): E

release: function(exclusive self: Allocator<E>, value: E): nil

Emittableinterface#

interface events.Emittable
end

What a declaration becomes by deriving events.Event.

The bound an event type parameter carries, so a source refuses a record that never derived the event contract before anything runs.

MessageBusrecord#

record events.MessageBus<A> is events.Source<A>
    observers: events.Observers<A>
    observe: function<E is events.Emittable>(
        exclusive self: MessageBus<A>,
        address: A,
        event: Type<E>,
        callback: events.Observer<E>,
        id: string?
    ): nil
    observeOnce: function<E is events.Emittable>(
        exclusive self: MessageBus<A>,
        address: A,
        event: Type<E>,
        callback: events.Observer<E>,
        id: string?
    ): nil
    stopObserving: function<E is events.Emittable>(
        exclusive self: MessageBus<A>,
        address: A,
        event: Type<E>,
        callbackOrId: events.Observer<E> | string
    ): boolean
    hasObservers: function<E is events.Emittable>(self: MessageBus<A>, address: A, event: Type<E>): boolean
    emit: function<E is events.Emittable>(
        exclusive self: MessageBus<A>,
        address: A,
        event: Type<E>,
        ...: unpackof Construction(E)
    ): nil
    deliver: function<E is events.Emittable>(
        exclusive self: MessageBus<A>,
        address: A,
        event: Type<E>,
        instance: E
    ): nil
    clearAddress: function(exclusive self: MessageBus<A>, address: A): nil
    reset: function(exclusive self: MessageBus<A>): nil
    setAllocator: function<E is events.Emittable>(
        exclusive self: MessageBus<A>,
        event: Type<E>,
        allocator: events.Allocator<E>
    ): nil
end

A source that is nothing but its observers.

Every method forwards to the function of the same name, passing the bus as the source that owns observer state.

Type parameters

Methods

observe: function<E is events.Emittable>(
    exclusive self: MessageBus<A>,
    address: A,
    event: Type<E>,
    callback: events.Observer<E>,
    id: string?
): nil

observeOnce: function<E is events.Emittable>(
    exclusive self: MessageBus<A>,
    address: A,
    event: Type<E>,
    callback: events.Observer<E>,
    id: string?
): nil

stopObserving: function<E is events.Emittable>(
    exclusive self: MessageBus<A>,
    address: A,
    event: Type<E>,
    callbackOrId: events.Observer<E> | string
): boolean

hasObservers: function<E is events.Emittable>(self: MessageBus<A>, address: A, event: Type<E>): boolean

emit: function<E is events.Emittable>(
    exclusive self: MessageBus<A>,
    address: A,
    event: Type<E>,
    ...: unpackof Construction(E)
): nil

deliver: function<E is events.Emittable>(
    exclusive self: MessageBus<A>,
    address: A,
    event: Type<E>,
    instance: E
): nil

clearAddress: function(exclusive self: MessageBus<A>, address: A): nil

reset: function(exclusive self: MessageBus<A>): nil

setAllocator: function<E is events.Emittable>(
    exclusive self: MessageBus<A>,
    event: Type<E>,
    allocator: events.Allocator<E>
): nil

Fields

observers: events.Observers<A>

Observertype#

type events.Observer<E> = function(borrows event: E): nil

An observer of one event type.

The event is borrowed for the call: it may be read and written, and cannot be stored or returned. State beyond the event is explicit: capture it in the observer or carry it as an event field.

Type parameters

Observersrecord#

record events.Observers<A>
    readonly count: integer
end

Observer registrations for one source, keyed by address and event identity.

A source holds one of these in its observers field. Nothing exists for an address until something observes there, so a world of millions of entities pays for the observers it has and not for the entities it could have.

Type parameters

Fields

count: integer

Sourceinterface#

interface events.Source<A>
    observers: events.Observers<A>
end

Something that owns observer state.

A bus or a world implements this by holding an observers field; the dispatch functions take the source exclusively and reach its state through that field. The source is not implicitly passed to observers.

Type parameters

Fields

observers: events.Observers<A>

events.clearAddressfunction#

function events.clearAddress<A, S is events.Source<A>>(exclusive source: S, borrows address: A): nil

Removes every registration at one address.

A delivery in flight at that address finishes the list it already holds; the next emission there finds nothing. Registrations at other addresses are untouched, which is how a world clears an entity without losing what observes the world itself.

Type parameters

Arguments

Returns

events.deliverfunction#

function events.deliver<A, S is events.Source<A>, E is events.Emittable>(exclusive source: S, borrows address: A, event: Type<E>, instance: E): nil

Delivers an event instance the caller already holds.

The instance is neither acquired nor released: what the caller built stays the caller's, and is handed to each observer as the borrow its contract names. Everything else is as emit.

Type parameters

Arguments

Returns

Raises

• what an observer raised

events.emitfunction#

function events.emit<A, S is events.Source<A>, E is events.Emittable>(exclusive source: S, borrows address: A, event: Type<E>, ...: unpackof Construction(E)): nil

Constructs an event into the source's storage and delivers it.

Nothing is acquired, initialized, or run when no observer is registered at the address for the event: the argument expressions are evaluated as they are for any call, and that is all. Otherwise storage is leased from the event's allocator, the declaration's initializer fills it from the arguments, applying a field default where an argument is nil, every observer registered when the delivery began runs in order, and the lease is released whether the delivery returned, raised, or was cancelled while an observer was suspended.

Type parameters

Arguments

Returns

Raises

• what an observer or the initializer raised, after the lease is released

events.Eventcomptime function#

comptime function events.Event(info: nupp.derive.Info): nupp.derive.Result<events.Emittable>

Marks a record or a fixed-layout struct as an event.

The derive records the event's name and representation, and asks the compiler for the declaration's initializer: its constructor body, or its field list, run against storage a source already holds. A declaration with several constructors, one whose constructor keeps self or moves an owner into it, an affine field, or a generic owner is refused, since none of those can run against reused storage.

Arguments

Returns

events.hasObserversfunction#

function events.hasObservers<A, S is events.Source<A>, E is events.Emittable>(borrows source: S, borrows address: A, event: Type<E>): boolean

Whether anything observes one event type at one address.

Type parameters

Arguments

Returns

events.idfunction#

function events.id<E is events.Emittable>(event: Type<E>): integer

The identity an event type has in this runtime.

Assigned once, the first time a source, id, or name asks, from a counter local to this Lua state. It is stable for the life of the state and is never a persistent or wire identity.

Type parameters

Arguments

Returns

Raises

• when the type did not derive events.Event

events.namefunction#

function events.name<E is events.Emittable>(event: Type<E>): string

The name an event type registered under.

Type parameters

Arguments

Returns

Raises

• when the type did not derive events.Event

events.observefunction#

function events.observe<A, S is events.Source<A>, E is events.Emittable>(exclusive source: S, borrows address: A, event: Type<E>, callback: events.Observer<E>, id: string?): nil

Registers an observer of one event type at one address.

Observers run in registration order. A name lets stopObserving remove this registration by name; a name already registered at the same address and event is an error, since the second could never be removed alone.

Type parameters

Arguments

Returns

Raises

• when the type did not derive events.Event, or the name is taken

events.observeOncefunction#

function events.observeOnce<A, S is events.Source<A>, E is events.Emittable>(exclusive source: S, borrows address: A, event: Type<E>, callback: events.Observer<E>, id: string?): nil

Registers an observer that is consumed before its first delivery.

The registration is tombstoned before the callback is invoked, so a nested or interleaved delivery of the same event never reaches it again, whatever the callback goes on to do.

Type parameters

Arguments

Returns

Raises

• when the type did not derive events.Event, or the name is taken

events.resetfunction#

function events.reset<A, S is events.Source<A>>(exclusive source: S): nil

Removes every registration at every address.

Allocators are left alone: an arena the caller installed is still theirs, and the source's own storage is reused by the next emission.

Type parameters

Arguments

Returns

events.setAllocatorfunction#

function events.setAllocator<A, S is events.Source<A>, E is events.Emittable>(exclusive source: S, event: Type<E>, allocator: events.Allocator<E>): nil

Installs the storage one event type is constructed into at this source.

The allocator is the caller's: it must outlive the source's use of it, and the source never resets or closes it. Replacing one while a delivery holds storage from it is refused, since the lease would have nowhere to return.

Type parameters

Arguments

Returns

Raises

• when a delivery of that event is active

events.stopObservingfunction#

function events.stopObserving<A, S is events.Source<A>, E is events.Emittable>(exclusive source: S, borrows address: A, event: Type<E>, callbackOrId: events.Observer<E> | string): boolean

Removes registrations at one address and event.

Given a name, the first registration with that name goes; given a callback, every registration of it goes. A removal during a delivery takes effect at once for anything not yet reached and is compacted out after the outermost delivery leaves. A caller removing by callback keeps the value it registered: a short function is a fresh object each time its expression runs.

Type parameters

Arguments

Returns