EventHandler

Compile-time switch for copy-on-write handler lists.

When true (default), the per-type handler array is immutable: on/off/ remove_all_handlers build a fresh array and swap it in under the lock, rather than mutating the shared array in place. This lets _emit take its snapshot by reading the reference instead of duping on every emit — since emits vastly outnumber subscription changes, this moves the copy off the hot path.

Because the captured array is never mutated, _emit reads its snapshot without taking the lock — a single atomic pointer load. The mutex only serializes writers against each other (their dup→mutate→swap is a read-modify-write that would otherwise lose updates).

Correctness holds because no array is mutated in place while a concurrent (or reentrant) _emit might be iterating it: a writer always publishes a new array, and an in-flight emit keeps iterating its captured snapshot — the same semantics the previous dup provided. Relies on pointer-sized reference assignment being atomic (true on all supported targets).

Set to false to restore the original in-place mutation + per-emit dup; when disabled the copy-on-write code is not generated.

Compile-time switch for the "skip emit when nothing is subscribed" fast path.

When true (default), emit/_emit return immediately if the event has no registered handlers (neither its concrete type nor the catch-all AnyEvent), avoiding the per-emit reentrant-mutex lock and handler-array dup. Matters for emit-heavy workloads (e.g. a UI render loop) with no listeners.

The fast path reads Array#empty? without holding the lock — a benign race already inherent to the snapshot design (a handler added concurrently with an emit isn't guaranteed to observe that emit). Set to false to restore unconditional locking; a compile-time constant so the guard generates no code at all when disabled.

Logger used to report failures that occur while dispatching a handler asynchronously. See Wrapper#call_async for the async error contract.

Per Crystal's Log conventions, emits nothing until the application configures a backend (e.g. Log.setup_from_env). Applications that care about async handler failures should configure one to see these entries.

Asynchronous execution flag; default false.

Controls whether event handlers execute synchronously one by one, or asynchronously in Fibers.

EventHandler.async? # => false
EventHandler.async = true

Only affects the default; can be overriden per-handler via the async argument when subscribing.

Asynchronous execution flag; default false.

Controls whether event handlers execute synchronously one by one, or asynchronously in Fibers.

EventHandler.async? # => false
EventHandler.async = true

Only affects the default; can be overriden per-handler via the async argument when subscribing.

Asynchronous execution flag for #waited events; default false.

Controls whether implicitly created handlers that forward events through channels execute synchronously or asynchronously.

EventHandler.async_send? # => false
EventHandler.async_send = true

Only affects the default; can be overriden per-#wait via async_send.

Asynchronous execution flag for #waited events; default false.

Controls whether implicitly created handlers that forward events through channels execute synchronously or asynchronously.

EventHandler.async_send? # => false
EventHandler.async_send = true

Only affects the default; can be overriden per-#wait via async_send.

Default insertion index for a handler inserted at the beginning of the list; default 0.

Changing this can cause "Index out of bounds" exceptions if not done carefully; rarely needs changing.

Default insertion index for a handler inserted at the beginning of the list; default 0.

Changing this can cause "Index out of bounds" exceptions if not done carefully; rarely needs changing.

Default insertion index for a handler inserted at the end of the list; default -1.

Changing this can cause "Index out of bounds" exceptions if not done carefully; rarely needs changing.

Default insertion index for a handler inserted at the end of the list; default -1.

Changing this can cause "Index out of bounds" exceptions if not done carefully; rarely needs changing.

RemoveHandlerEvent control flag for #remove_all; default true.

Controls whether handlers removed by #remove_all emit a RemoveHandlerEvent. Disabling can make sense at application shutdown when running those handlers no longer matters.

EventHandler.emit_on_remove_all? # => true
EventHandler.emit_on_remove_all = false

RemoveHandlerEvent control flag for #remove_all; default true.

Controls whether handlers removed by #remove_all emit a RemoveHandlerEvent. Disabling can make sense at application shutdown when running those handlers no longer matters.

EventHandler.emit_on_remove_all? # => true
EventHandler.emit_on_remove_all = false

Emits event of type.

When EMIT_SKIP_WHEN_NO_HANDLERS, emit gains a fast path: if neither this concrete type nor the catch-all AnyEvent has any handler, it returns immediately. It's @[AlwaysInline] so, in the common no-subscriber case, the guard folds into the caller as two @size == 0 comparisons — no call into _emit, no lock, no allocation. With the constant off, neither the annotation nor the guard is generated and emit is the original two-line dispatch.

Emits event of type.

When EMIT_SKIP_WHEN_NO_HANDLERS, emit gains a fast path: if neither this concrete type nor the catch-all AnyEvent has any handler, it returns immediately. It's @[AlwaysInline] so, in the common no-subscriber case, the guard folds into the caller as two @size == 0 comparisons — no call into _emit, no lock, no allocation. With the constant off, neither the annotation nor the guard is generated and emit is the original two-line dispatch.

Emits event of type.

When EMIT_SKIP_WHEN_NO_HANDLERS, emit gains a fast path: if neither this concrete type nor the catch-all AnyEvent has any handler, it returns immediately. It's @[AlwaysInline] so, in the common no-subscriber case, the guard folds into the caller as two @size == 0 comparisons — no call into _emit, no lock, no allocation. With the constant off, neither the annotation nor the guard is generated and emit is the original two-line dispatch.

Emits event of type event.class

Emits event of type.

When EMIT_SKIP_WHEN_NO_HANDLERS, emit gains a fast path: if neither this concrete type nor the catch-all AnyEvent has any handler, it returns immediately. It's @[AlwaysInline] so, in the common no-subscriber case, the guard folds into the caller as two @size == 0 comparisons — no call into _emit, no lock, no allocation. With the constant off, neither the annotation nor the guard is generated and emit is the original two-line dispatch.

Returns Nil, unconditionally: with no listener the event object is never built (see below), so there would be nothing to return, and a return type that depends on whether anyone happens to be subscribed is not a usable contract. A caller that needs the emitted object back constructs it itself and uses the emit(type, event) form, which always returns it.

Emits event of type.

When EMIT_SKIP_WHEN_NO_HANDLERS, emit gains a fast path: if neither this concrete type nor the catch-all AnyEvent has any handler, it returns immediately. It's @[AlwaysInline] so, in the common no-subscriber case, the guard folds into the caller as two @size == 0 comparisons — no call into _emit, no lock, no allocation. With the constant off, neither the annotation nor the guard is generated and emit is the original two-line dispatch.

Returns Nil, unconditionally: with no listener the event object is never built (see below), so there would be nothing to return, and a return type that depends on whether anyone happens to be subscribed is not a usable contract. A caller that needs the emitted object back constructs it itself and uses the emit(type, event) form, which always returns it.

Emits event of type.

When EMIT_SKIP_WHEN_NO_HANDLERS, emit gains a fast path: if neither this concrete type nor the catch-all AnyEvent has any handler, it returns immediately. It's @[AlwaysInline] so, in the common no-subscriber case, the guard folds into the caller as two @size == 0 comparisons — no call into _emit, no lock, no allocation. With the constant off, neither the annotation nor the guard is generated and emit is the original two-line dispatch.

Returns Nil, unconditionally: with no listener the event object is never built (see below), so there would be nothing to return, and a return type that depends on whether anyone happens to be subscribed is not a usable contract. A caller that needs the emitted object back constructs it itself and uses the emit(type, event) form, which always returns it.

Returns the list of handlers for event type.

Returns the list of handlers for event type.

Returns the list of handlers for event type.

Whether any handler is registered for type. Allocation-free (unlike handlers(type).any?, which dups the COW list).

Whether any handler is registered for type. Allocation-free (unlike handlers(type).any?, which dups the COW list).

Whether any handler is registered for type. Allocation-free (unlike handlers(type).any?, which dups the COW list).

Removes the handler behind subscription — the subscription-typed spelling of off(type, wrapper); returns the removed wrapper, or nil when it was no longer registered (or the subscription carries no wrapper).

Removes handler from the list of handlers for event type.

Removes handler from the list of handlers for event type.

Removes handler from the list of handlers for event type.

Removes handler from the list of handlers for event type.

Removes all handlers for event type.

If emit is false, RemoveHandlerEvents are not emitted.

If emit is true, a RemoveHandlerEvent is emitted once for every distinct Wrapper object removed. See README for details.

Removes the handler behind subscription — the subscription-typed spelling of off(type, wrapper); returns the removed wrapper, or nil when it was no longer registered (or the subscription carries no wrapper).

Removes handler from the list of handlers for event type.

Removes handler from the list of handlers for event type.

Removes handler from the list of handlers for event type.

Removes handler from the list of handlers for event type.

Removes all handlers for event type.

If emit is false, RemoveHandlerEvents are not emitted.

If emit is true, a RemoveHandlerEvent is emitted once for every distinct Wrapper object removed. See README for details.

Removes the handler behind subscription — the subscription-typed spelling of off(type, wrapper); returns the removed wrapper, or nil when it was no longer registered (or the subscription carries no wrapper).

Removes handler from the list of handlers for event type.

Removes handler from the list of handlers for event type.

Removes handler from the list of handlers for event type.

Removes handler from the list of handlers for event type.

Removes all handlers for event type.

If emit is false, RemoveHandlerEvents are not emitted.

If emit is true, a RemoveHandlerEvent is emitted once for every distinct Wrapper object removed. See README for details.

Adds handler to the list of handlers for event type.

Returns an EventHandler::Subscription — a self-contained disconnect handle: sub.off removes exactly this handler, with no need to restate the event type or hold the Wrapper (cf. Qt's QMetaObject::Connection). The Wrapper itself still flows to AddHandlerEvent/RemoveHandlerEvent listeners, and the off(type, handler/hash/at) forms keep working for callers that kept those instead.

Re-registers the Wrapper behind subscription — the subscription-typed spelling of on(type, wrapper). Raises ArgumentError when the subscription carries no wrapper (see Subscription#wrapper).

Removes the handler behind subscription — the subscription-typed spelling of off(type, wrapper); returns the removed wrapper, or nil when it was no longer registered (or the subscription carries no wrapper).

Removes the handler behind subscription — the subscription-typed spelling of off(type, wrapper); returns the removed wrapper, or nil when it was no longer registered (or the subscription carries no wrapper).

Adds an autogenerated handler which sends emitted events to channel

Adds handler to the list of handlers for event type.

Returns an EventHandler::Subscription — a self-contained disconnect handle: sub.off removes exactly this handler, with no need to restate the event type or hold the Wrapper (cf. Qt's QMetaObject::Connection). The Wrapper itself still flows to AddHandlerEvent/RemoveHandlerEvent listeners, and the off(type, handler/hash/at) forms keep working for callers that kept those instead.

Re-registers the Wrapper behind subscription — the subscription-typed spelling of on(type, wrapper). Raises ArgumentError when the subscription carries no wrapper (see Subscription#wrapper).

Removes the handler behind subscription — the subscription-typed spelling of off(type, wrapper); returns the removed wrapper, or nil when it was no longer registered (or the subscription carries no wrapper).

Removes the handler behind subscription — the subscription-typed spelling of off(type, wrapper); returns the removed wrapper, or nil when it was no longer registered (or the subscription carries no wrapper).

Adds an autogenerated handler which sends emitted events to channel

Adds handler to the list of handlers for event type.

Returns an EventHandler::Subscription — a self-contained disconnect handle: sub.off removes exactly this handler, with no need to restate the event type or hold the Wrapper (cf. Qt's QMetaObject::Connection). The Wrapper itself still flows to AddHandlerEvent/RemoveHandlerEvent listeners, and the off(type, handler/hash/at) forms keep working for callers that kept those instead.

Re-registers the Wrapper behind subscription — the subscription-typed spelling of on(type, wrapper). Raises ArgumentError when the subscription carries no wrapper (see Subscription#wrapper).

Removes the handler behind subscription — the subscription-typed spelling of off(type, wrapper); returns the removed wrapper, or nil when it was no longer registered (or the subscription carries no wrapper).

Removes the handler behind subscription — the subscription-typed spelling of off(type, wrapper); returns the removed wrapper, or nil when it was no longer registered (or the subscription carries no wrapper).

Adds an autogenerated handler which sends emitted events to channel

Per-event subscribe sugar, named after the event itself (the underscored last path component of the event class: event Clicked also defines on_clicked(&) on every emitter). Equivalent to on(EventHandler::AddHandlerEvent) { |e| ... }; returns the EventHandler::Subscription (see on). Emitters may shadow a generated method with a richer hand-written adapter (one yielding the event's payload instead of the event).

Skipped for an event nested inside another event class (e.g. a per-key KeyPress::<member> family): the last name component alone is ambiguous there — it can collide with an unrelated top-level event of the same name — and such families are typically generated and huge. Subscribe to those with the explicit on(Type) { } form. Options are keyword-only (bare *, like the block overload of on): with untyped positionals an emitter's own same-name sugar taking positional args (e.g. Crysterm's on_key('q', :escape)) would bind them to once/async here and fail deep in internal_insert instead of resolving to that overload.

Per-event subscribe sugar, named after the event itself (the underscored last path component of the event class: event Clicked also defines on_clicked(&) on every emitter). Equivalent to on(EventHandler::AnyEvent) { |e| ... }; returns the EventHandler::Subscription (see on). Emitters may shadow a generated method with a richer hand-written adapter (one yielding the event's payload instead of the event).

Skipped for an event nested inside another event class (e.g. a per-key KeyPress::<member> family): the last name component alone is ambiguous there — it can collide with an unrelated top-level event of the same name — and such families are typically generated and huge. Subscribe to those with the explicit on(Type) { } form. Options are keyword-only (bare *, like the block overload of on): with untyped positionals an emitter's own same-name sugar taking positional args (e.g. Crysterm's on_key('q', :escape)) would bind them to once/async here and fail deep in internal_insert instead of resolving to that overload.

Per-event subscribe sugar, named after the event itself (the underscored last path component of the event class: event Clicked also defines on_clicked(&) on every emitter). Equivalent to on(EventHandler::RemoveHandlerEvent) { |e| ... }; returns the EventHandler::Subscription (see on). Emitters may shadow a generated method with a richer hand-written adapter (one yielding the event's payload instead of the event).

Skipped for an event nested inside another event class (e.g. a per-key KeyPress::<member> family): the last name component alone is ambiguous there — it can collide with an unrelated top-level event of the same name — and such families are typically generated and huge. Subscribe to those with the explicit on(Type) { } form. Options are keyword-only (bare *, like the block overload of on): with untyped positionals an emitter's own same-name sugar taking positional args (e.g. Crysterm's on_key('q', :escape)) would bind them to once/async here and fail deep in internal_insert instead of resolving to that overload.

Adds handler to the list of handlers for event type; removed automatically after it triggers once. Returns an EventHandler::Subscription (see on); its #off is a no-op after the handler has auto-fired away.

Equivalent to on with argument once.

Adds handler to the list of handlers for event type; removed automatically after it triggers once. Returns an EventHandler::Subscription (see on); its #off is a no-op after the handler has auto-fired away.

Equivalent to on with argument once.

Adds an autogenerated handler which sends emitted events to channel; removed automatically after it triggers once.

Equivalent to on with argument once.

Adds handler to the list of handlers for event type; removed automatically after it triggers once. Returns an EventHandler::Subscription (see on); its #off is a no-op after the handler has auto-fired away.

Equivalent to on with argument once.

Adds handler to the list of handlers for event type; removed automatically after it triggers once. Returns an EventHandler::Subscription (see on); its #off is a no-op after the handler has auto-fired away.

Equivalent to on with argument once.

Adds an autogenerated handler which sends emitted events to channel; removed automatically after it triggers once.

Equivalent to on with argument once.

Adds handler to the list of handlers for event type; removed automatically after it triggers once. Returns an EventHandler::Subscription (see on); its #off is a no-op after the handler has auto-fired away.

Equivalent to on with argument once.

Adds handler to the list of handlers for event type; removed automatically after it triggers once. Returns an EventHandler::Subscription (see on); its #off is a no-op after the handler has auto-fired away.

Equivalent to on with argument once.

Adds an autogenerated handler which sends emitted events to channel; removed automatically after it triggers once.

Equivalent to on with argument once.

Removes all handlers for event type.

If emit is false, RemoveHandlerEvents are not emitted.

If emit is true, a RemoveHandlerEvent is emitted once for every distinct Wrapper object removed. See README for details.

Removes all handlers for event type.

If emit is false, RemoveHandlerEvents are not emitted.

If emit is true, a RemoveHandlerEvent is emitted once for every distinct Wrapper object removed. See README for details.

Removes all handlers for event type.

If emit is false, RemoveHandlerEvents are not emitted.

If emit is true, a RemoveHandlerEvent is emitted once for every distinct Wrapper object removed. See README for details.

Removes every handler this emitter carries, for every event type — the whole-object counterpart of remove_all_handlers(type). Use it when the emitter itself is being torn down and nothing subscribed to it should keep running (or keep the emitter, and whatever its handlers captured, alive).

Handlers this object registered on other emitters are unaffected — nothing links them back here. Cancel those through the Subscription/Subscriptions they returned.

emit controls RemoveHandlerEvent emission exactly as in remove_all_handlers(type, emit); it defaults to off here, since a torn-down emitter has no use for the notifications.

Blocks until event type is emitted and executes handler.

handler may be nil, in which case wait blocks until the event arrives and returns it without running any handler.

Blocks until event type is emitted and executes handler.

handler may be nil, in which case wait blocks until the event arrives and returns it without running any handler.

Blocks until event type is emitted and returns emitted event.

Blocks until event type is emitted and executes handler.

handler may be nil, in which case wait blocks until the event arrives and returns it without running any handler.

Blocks until event type is emitted and executes handler.

handler may be nil, in which case wait blocks until the event arrives and returns it without running any handler.

Blocks until event type is emitted and returns emitted event.

Blocks until event type is emitted and executes handler.

handler may be nil, in which case wait blocks until the event arrives and returns it without running any handler.

Blocks until event type is emitted and executes handler.

handler may be nil, in which case wait blocks until the event arrives and returns it without running any handler.

Blocks until event type is emitted and returns emitted event.

Creates events in a single line; every event is a class inheriting from EventHandler::Event.

Since events are classes, they can also be created manually. See EventHandler::Event for more details.

event MouseClick, x : ::Int32, y : ::Int32