classDocs / Emitter

Emitter

classsharedsource

Object → Emitter

A minimal event registry shared by every instance of a class.

Unlike Hook it has no stages, priorities or return values: emit calls each handler in attach order, in protected mode, so one failing handler is reported and never stops the others, and emits may nest freely.

Handlers are functions or callable objects, e.g. a Hook attached as a handler runs its own call with the emitted arguments.

Listener lists are created on the first attach and kept in the emitter itself (weak keys), objects without listeners cost nothing. A handler capturing its own object as an upvalue keeps that object alive (LuaJIT weak tables are not ephemerons), use the object passed to the handler instead.

lua

local events = Emitter( "Thing" )

function Thing:attach( event, handler ) events:attach( self, event, handler ) end

events:emit( thing, "open", thing )

Constructor

Emitter(name: string): Emitter

Fields

Name	Type	Description
`__mode`	`string`	= `"k"`

Methods

`__len`
`attach`	Attaches a handler for event_name on object.
`await`	Suspends the caller until event_name fires on object, then returns its arguments.
`clear`	Removes every handler of event_name on object, or of every event when event_name is nil.
`count`	Returns the number of handlers attached to event_name on object.
`detach`	Detaches a handler previously passed to attach or once.
`emit`	Calls every handler of event_name on object with ..., in attach order.
`once`	Attaches a one-shot handler, detached right before it runs.

#Emitter:__len

source

function Emitter:__len()

#Emitter:attach

sharedsource

function Emitter:attach(object: any, event_name: string, handler: Emitter.Handler)

Attaches a handler for event_name on object. Attaching the same handler twice is a no-op.

Parameters

Name	Type	Description
`object`	`any`	The object the handler listens on.
`event_name`	`string`	The event name.
`handler`	`Emitter.Handler`	The callback or callable object, receives the `emit` arguments.

#Emitter:await

sharedasyncsource

async function Emitter:await(object: any, event_name: string, abort_event?: string, abort_message?: string): any

Suspends the caller until event_name fires on object, then returns its arguments.

When abort_event fires first, both listeners are detached and abort_message (or a generic message) is thrown instead.

At most the first 6 emitted values are returned, keep awaitable events within that.

Parameters

Name	Type	Description
`object`	`any`	The object to wait on.
`event_name`	`string`	The event to wait for.
`abort_event`optional	`string`	An event that cancels the wait, e.g. `"close"`.
`abort_message`optional	`string`	The error message thrown on abort.

Returns

Type	Name	Description
`any`	`...`	The arguments `event` was emitted with.

#Emitter:clear

sharedsource

function Emitter:clear(object: any, event_name?: string)

Removes every handler of event_name on object, or of every event when event_name is nil.

Handlers still pending in a running emit of a cleared event are skipped.

Parameters

Name	Type	Description
`object`	`any`	The object to clear.
`event_name`optional	`string`	The event name, or `nil` for all events.

#Emitter:count

sharednodiscardsource

function Emitter:count(object: any, event_name: string): integer

Returns the number of handlers attached to event_name on object.

Parameters

Name	Type	Description
`object`	`any`	The object to inspect.
`event_name`	`string`	The event name.

Returns

Type	Name	Description
`integer`	`count`

#Emitter:detach

sharedsource

function Emitter:detach(object: any, event_name: string, handler: Emitter.Handler): boolean

Detaches a handler previously passed to attach or once.

Parameters

Name	Type	Description
`object`	`any`	The object the handler listens on.
`event_name`	`string`	The event name.
`handler`	`Emitter.Handler`	The exact handler reference.

Returns

Type	Name	Description
`boolean`	`removed`	`true` if the handler was attached.

#Emitter:emit

sharedsource

function Emitter:emit(object: any, event_name: string, ...: any)

Calls every handler of event_name on object with ..., in attach order.

Each handler runs in protected mode: errors are reported and the rest still run. Non-function handlers are called through their __call metamethod with themselves first. Handlers attached during the emit run from the next emit on.

Parameters

Name	Type	Description
`object`	`any`	The object the event fires on.
`event_name`	`string`	The event name.
`...`	`any`	Arguments forwarded to every handler.

#Emitter:once

sharedsource

function Emitter:once(object: any, event_name: string, handler: Emitter.Handler)

Attaches a one-shot handler, detached right before it runs.

It can still be removed with detach using the same handler reference.

Parameters

Name	Type	Description
`object`	`any`	The object the handler listens on.
`event_name`	`string`	The event name.
`handler`	`Emitter.Handler`	The callback or callable object, receives the `emit` arguments.