Broadcaster¶
Namespace:
SideXP.Broadcaster
Main entry point of the Broadcast system.
Remarks
Internally, this class just shares a static instance of EventBus.
Properties¶
Default¶
The shared default bus. Created lazily so the façade also works in edit mode, and recreated when entering play mode so a disabled domain reload can't leak state from a previous play session.
Methods¶
Emit<T>(T)¶
Delivers a signal synchronously to every current listener, in registration order. Returns once all listeners have run. Zero listeners is fine (silent). A throwing listener never stops the others (its exception is logged and the rest still run).
Type parameters
T: The exact signal type. Dispatch is exact-type only (a derived signal never reaches a base-type listener).
Parameters
signal: The signal instance (its fields are the payload).
Subscribe<T>(object, Action<T>, bool)¶
Registers a listener for a signal type.
Type parameters
T: The exact signal type to listen for.
Parameters
owner: The owner of this registration (powers UnregisterAll and diagnostics).listener: The callback invoked on each emit.init: If true and a provider forTis alive, the listener is invoked immediately with that provider's current value (in addition to future emits). Does nothing if no provider is alive. Only sees providers registered before this call.
Returns
A handle that unregisters this listener when disposed.
Unsubscribe<T>(Action<T>)¶
Removes a previously registered signal listener, matched by Equals (target + method, never reference equality, so a method group re-created at the call site still matches). Removes the first matching active registration.
Type parameters
T: The signal type the listener was registered for.
Parameters
listener: The same listener (a method group re-created at the call site still matches).
Returns
True if a matching registration was found and removed.
Provide<T>(object, Func<T>, bool)¶
Registers a provider for a signal type. The state owner's answer to "what is the current value?". A listener subscribing with init: true pulls this value immediately, and TryGetCurrent``1 reads it on demand. The provider is invoked lazily (never cached), so its value is never stale, and it dies with its owner.
Type parameters
T: The exact signal type this provider supplies the current value for.
Parameters
owner: The owner of this registration.provider: Returns the current value on demand.replace: By default, if you try to add a provider while another one already exists, this call is ignored. If enabled, this provider supersedes it.
Returns
A handle that unregisters this provider when disposed. When a provider already exists and replace is false, returns an inactive handle instead.
TryGetCurrent<T>(T)¶
Reads the current value for a signal type from its provider, without subscribing. Returns false (and current is default) if no provider is alive for the type.
Type parameters
T: The signal type to read the current value of.
Parameters
current: The provider's current value, ordefaultif none.
Returns
True if a provider answered, false otherwise.
Perform<T>(object, Action<T>)¶
Registers an instant performer for a cue type. It runs synchronously when the cue is sent and completes immediately.
Type parameters
T: The exact cue type to perform.
Parameters
owner: The owner of this registration.performer: The reaction, run synchronously on each cue.
Returns
A handle that unregisters this performer when disposed.
Perform<T>(object, Func<T, Awaitable>)¶
Registers a durative performer for a cue type. It starts synchronously when the cue is sent and returns an Awaitable that completes when its reaction finishes; the cue's completion waits for it.
Parameters
performer: The reaction; its first synchronous stretch runs on send, and the returned awaitable marks completion.
Returns
A handle that unregisters this performer when disposed.
Perform<T>(object, CuePerformerDelegate<T>)¶
Registers a callback-style performer for a cue type, for coroutine/callback code that doesn't want to author an Awaitable. It starts synchronously and receives a done callback it must invoke when its reaction finishes; the cue's completion waits for that call.
Parameters
performer: The reaction, receiving the cue and adonecallback. It must eventually calldoneor the cue never completes for this performer (until the performer is unregistered).
Returns
A handle that unregisters this performer when disposed.
Cue<T>(T, CancellationToken)¶
Sends a cue: every current performer starts synchronously in registration order (an instant performer runs fully, a durative/callback one runs its synchronous stretch), then the returned awaitable resolves when the last performer finishes (when-all). Zero performers resolves instantly. A throwing performer is isolated (logged with its owner as context) and neither holds up nor kills the others. The awaitable resolves as cancelled if cancellation fires (the cancellation fans out to every in-flight performer). A performer unregistered mid-cue resolves rather than hanging; the cue still completes on the rest.
Type parameters
T: The exact cue type.
Parameters
cue: The cue instance (its fields are the payload).cancellation: Cancels the cue: resolves the awaitable as cancelled and fans out to every in-flight performer.
Returns
An awaitable that completes when every performer has finished.
Obey<T>(object, Action<T>, bool)¶
Registers the single handler that performs a command. A command has exactly one handler: a second registration for the same type is ignored.
Type parameters
T: The exact command type to handle.
Parameters
owner: The owner of this registration.handler: Performs the action when the command is ordered.replace: By default, if you try to add a handler while another one already exists, this call is ignored. If enabled, this handler supersedes it (for an intentional hand-off, eg. across an additive scene load).
Returns
A handle that unregisters this handler when disposed. When a handler already exists and replace is false, returns an inactive handle instead.
Obey<T>(object, Func<T, Awaitable>, bool)¶
public static SubscriptionHandle Obey<T>(object owner, Func<T, Awaitable> handler, bool replace = false)
Registers the single async handler that performs a command. A command has exactly one handler: a second registration for the same type is ignored. Reachable only through OrderAsync1](EventBus.md#orderasync-t-t-cancellationtoken) (a synchronous [Order1 can't wait for it).
Parameters
handler: Performs the action and returns anAwaitablethat completes when it's done.
Obey<T, TResult>(object, Func<T, TResult>, bool)¶
public static SubscriptionHandle Obey<T, TResult>(object owner, Func<T, TResult> handler, bool replace = false)
Registers the single handler that performs a command and reports its outcome. A command has exactly one handler: a second registration for the same type is ignored.
Type parameters
T: The exact command type to handle.TResult: The outcome the action produces.
Parameters
owner: The owner of this registration.handler: Performs the action and returns its outcome.replace: By default, if you try to add a handler while another one already exists, this call is ignored. If enabled, this handler supersedes it (for an intentional hand-off, eg. across an additive scene load).
Returns
A handle that unregisters this handler when disposed. When a handler already exists and replace is false, returns an inactive handle instead.
Obey<T, TResult>(object, Func<T, Awaitable<TResult>>, bool)¶
public static SubscriptionHandle Obey<T, TResult>(object owner, Func<T, Awaitable<TResult>> handler, bool replace = false)
Registers the single async handler that performs a command and reports its outcome. A command has exactly one handler: a second registration for the same type is ignored. Reachable only through OrderAsync1](EventBus.md#orderasync-tresult-icommand-tresult-cancellationtoken) (a synchronous [Order1 can't wait for it).
Parameters
handler: Performs the action and returns anAwaitable<TResult>carrying its outcome.
Order<T>(T)¶
Orders a command, invoking its single handler synchronously. Returns whether a handler performed it. With no handler registered, logs a dev-build error and returns false.
Type parameters
T: The exact command type.
Parameters
command: The command instance (its fields are the payload).
Returns
True if a handler performed the command.
Order<TResult>(ICommand<TResult>)¶
Orders a command and returns the outcome its handler produced, invoked synchronously. A handler is mandatory: with none registered this throws (a valued order has no outcome to report without one).
Type parameters
TResult: The outcome the action produces.
Parameters
command: The command instance, typed as its interface soTResultis inferred at the call site.
Returns
The outcome the handler produced.
Exceptions
InvalidOperationException: No handler is registered for the command type.
OrderAsync<T>(T, CancellationToken)¶
public static Awaitable OrderAsync<T>(T command, CancellationToken cancellation = default(CancellationToken))
Orders a command and awaits its completion. Works on both sync and async handlers (a sync handler completes immediately). The awaitable resolves as cancelled if cancellation fires or if the handler is unregistered before it finishes, and faulted if the handler throws (it never hangs).
Parameters
cancellation: Cancels the caller's wait (the handler itself manages its own cancellation).
Returns
An awaitable that completes when the handler finishes. Completes immediately (dev-build error) when no handler is registered. There is no outcome to report for a void command.
OrderAsync<TResult>(ICommand<TResult>, CancellationToken)¶
public static Awaitable<TResult> OrderAsync<TResult>(ICommand<TResult> command, CancellationToken cancellation = default(CancellationToken))
Orders a command and awaits the outcome its handler produces. Works on both sync and async handlers (a sync handler completes immediately). The awaitable resolves as cancelled if cancellation fires or if the handler is unregistered before it finishes, and faulted if the handler throws or no handler is registered (it never hangs).
Parameters
cancellation: Cancels the caller's wait (the handler itself manages its own cancellation).
Returns
An awaitable carrying the handler's outcome.
Answer<T, TResult>(object, Func<T, TResult>, bool)¶
public static SubscriptionHandle Answer<T, TResult>(object owner, Func<T, TResult> handler, bool replace = false)
Registers the single handler that answers a request. A request has exactly one handler: a second registration for the same type is ignored.
Type parameters
T: The exact request type to answer.TResult: The type of the answer.
Parameters
owner: The owner of this registration.handler: Produces the answer. By convention it must not mutate state (asking is always safe).replace: By default, if you try to add a handler while another one already exists, this call is ignored. If enabled, this handler supersedes it (for an intentional hand-off, eg. across an additive scene load).
Returns
A handle that unregisters this handler when disposed. When a handler already exists and replace is false, returns an inactive handle instead.
Answer<T, TResult>(object, Func<T, Awaitable<TResult>>, bool)¶
public static SubscriptionHandle Answer<T, TResult>(object owner, Func<T, Awaitable<TResult>> handler, bool replace = false)
Registers the single async handler that answers a request. A request has exactly one handler: a second registration for the same type is ignored. Reachable only through AskAsync1](EventBus.md#askasync-tresult-irequest-tresult-cancellationtoken) (a synchronous [Ask1 can't wait for it).
Parameters
handler: Produces the answer as anAwaitable<TResult>. By convention it must not mutate state.
Ask<TResult>(IRequest<TResult>)¶
Asks a request and returns its handler's answer, invoked synchronously. A handler is mandatory: with none registered this throws (a question with no answer has no value to return). Use TryAsk``1 to tolerate an unanswered request.
Type parameters
TResult: The type of the answer.
Parameters
request: The request instance, typed as its interface soTResultis inferred at the call site.
Returns
The handler's answer.
Exceptions
InvalidOperationException: No handler is registered for the request type.
TryAsk<TResult>(IRequest<TResult>, TResult)¶
Asks a request without requiring an answer. Returns whether a handler answered. result is the answer, or default if none.
Type parameters
TResult: The type of the answer.
Parameters
request: The request instance.result: The handler's answer, ordefaultif no handler is registered.
Returns
True if a handler answered.
AskAsync<TResult>(IRequest<TResult>, CancellationToken)¶
public static Awaitable<TResult> AskAsync<TResult>(IRequest<TResult> request, CancellationToken cancellation = default(CancellationToken))
Asks a request and awaits its handler's answer. Works on both sync and async handlers (a sync handler completes immediately). The awaitable resolves as cancelled if cancellation fires or if the handler is unregistered before it answers, and faulted if the handler throws or no handler is registered (it never hangs).
Parameters
cancellation: Cancels the caller's wait (the handler itself manages its own cancellation).
Returns
An awaitable carrying the handler's answer.
UnregisterAll(object)¶
Removes every registration made by the given owner.
Parameters
owner: The owner whose registrations to remove (compared by reference).
Returns
The number of registrations removed.
Clear()¶
Hard reset: removes every registration of every kind. The bus stores no payloads, so there is nothing else to clear.
Clear<T>()¶
Removes every registration for a single event type.
Type parameters
T: The event type to clear.