Class MessageBus
A messaging system that can have subscribers added to it, and send messages. When messages are sent, it will call any handlers that requested to handle messages of the proper types, based on the type-tree/interface-tree of the messages.
Inherited Members
Namespace: GoRogue.Messaging
Assembly: GoRogue.dll
Syntax
public class MessageBus
Constructors
View SourceMessageBus()
Constructor.
Declaration
public MessageBus()
Properties
View SourceSubscriberCount
Number of subscribers currently listening on this message bus.
Declaration
public int SubscriberCount { get; }
Property Value
Type | Description |
---|---|
int |
Methods
View SourceRegisterAllSubscribers<T>(T)
Adds the given subscriber to the message bus's handlers list, so its Handle function will be called when any messages of a type that the subscriber is subscribed to are sent via the Send<TMessage>(TMessage) function. Particularly when a handler is intended to have a shorter lifespan than the message bus, they MUST be unregistered via UnregisterAllSubscribers<T>(T) or another Unregister function when they are disposed of, to avoid the bus preventing the handler from being garbage collected.
Declaration
public T RegisterAllSubscribers<T>(T subscriber) where T : notnull
Parameters
Type | Name | Description |
---|---|---|
T | subscriber | Subscriber to add. |
Returns
Type | Description |
---|---|
T | The subscriber that was added, in case a reference is needed to later call UnregisterAllSubscribers<T>(T). |
Type Parameters
Name | Description |
---|---|
T | Type of the subscriber. This is typically inferred by the compiler, and really only affects the returned type (for chaining). |
Remarks
This is typically a good (safe) registration method to use by default. However, if you know that your subscriber types will only implement one variation of ISubscriber, or you need registration to happen as quickly as possible, then you should instead consider calling RegisterSubscriber<TMessage>(ISubscriber<TMessage>) once for each variation of ISubscriber your subscriber implements. This function uses reflection to figure out what versions of ISubscriber the parameter implements, so can be somewhat slow compared to RegisterSubscriber.
RegisterSubscriber<TMessage>(ISubscriber<TMessage>)
Adds the given subscriber to the message bus's handlers list, so its Handle function will be called when any messages
that can cast to TMessage
are sent via the Send<TMessage>(TMessage) function.
Particularly when a handler is intended to have a shorter lifespan than the message bus, they MUST be unregistered via
UnregisterSubscriber<TMessage>(ISubscriber<TMessage>) or another Unregister function when they are disposed
of, to avoid the bus preventing the handler from being garbage collected.
Declaration
public ISubscriber<TMessage> RegisterSubscriber<TMessage>(ISubscriber<TMessage> subscriber)
Parameters
Type | Name | Description |
---|---|---|
ISubscriber<TMessage> | subscriber | Subscriber to add. |
Returns
Type | Description |
---|---|
ISubscriber<TMessage> | The subscriber that was added, in case a reference is needed to later call UnregisterSubscriber<TMessage>(ISubscriber<TMessage>). |
Type Parameters
Name | Description |
---|---|
TMessage | Type of message the subscriber is handling. This can typically be inferred by the compiler, barring the case detailed in the ISubscriber<TMessage> remarks where one class subscribes to multiple message types. |
Remarks
Particularly if your handling class subscribes to multiple message types, you may want to consider using RegisterAllSubscribers<T>(T) instead; however that function uses reflection so will be slower than just calling this function once per implementation of ISubscriber.
Send<TMessage>(TMessage)
Sends the specified message on the message bus, automatically calling any appropriate registered handlers.
Declaration
public void Send<TMessage>(TMessage message) where TMessage : notnull
Parameters
Type | Name | Description |
---|---|---|
TMessage | message |
Type Parameters
Name | Description |
---|---|
TMessage |
TryRegisterAllSubscribers<T>(T)
Tries to add the given subscriber to the message bus's handlers list, so its Handle function will be called when any messages of a type that the subscriber is subscribed to are sent via the Send<TMessage>(TMessage) function. Particularly when a handler is intended to have a shorter lifespan than the message bus, they MUST be unregistered via UnregisterAllSubscribers<T>(T) or another Unregister function when they are disposed of, to avoid the bus preventing the handler from being garbage collected.
Declaration
public bool TryRegisterAllSubscribers<T>(T subscriber) where T : notnull
Parameters
Type | Name | Description |
---|---|---|
T | subscriber | Subscriber to add. |
Returns
Type | Description |
---|---|
bool | True if the subscriber was added; false if it was already identically registered. |
Type Parameters
Name | Description |
---|---|
T | Type of the subscriber. This is typically inferred by the compiler, and really only affects the returned type (for chaining). |
Remarks
This is typically a good (safe) registration method to use by default. However, if you know that your subscriber types will only implement one variation of ISubscriber, or you need registration to happen as quickly as possible, then you should instead consider calling TryRegisterSubscriber<TMessage>(ISubscriber<TMessage>) once for each variation of ISubscriber your subscriber implements. This function uses reflection to figure out what versions of ISubscriber the parameter implements, so can be somewhat slow compared to TryRegisterSubscriber.
TryRegisterSubscriber<TMessage>(ISubscriber<TMessage>)
Tries to add the given subscriber to the message bus's handlers list, so its Handle function will be called when any messages
that can cast to TMessage
are sent via the Send<TMessage>(TMessage) function.
Particularly when a handler is intended to have a shorter lifespan than the message bus, they MUST be unregistered via
UnregisterSubscriber<TMessage>(ISubscriber<TMessage>) or another Unregister function when they are disposed of,
to avoid the bus preventing the handler from being garbage collected.
Declaration
public bool TryRegisterSubscriber<TMessage>(ISubscriber<TMessage> subscriber)
Parameters
Type | Name | Description |
---|---|---|
ISubscriber<TMessage> | subscriber | Subscriber to add. |
Returns
Type | Description |
---|---|
bool | True if the subscriber was added; false if it was already identically registered. |
Type Parameters
Name | Description |
---|---|
TMessage | Type of message the subscriber is handling. This can typically be inferred by the compiler, barring the case detailed in the ISubscriber<TMessage> remarks where one class subscribes to multiple message types. |
Remarks
Particularly if your handling class subscribes to multiple message types, you may want to consider using TryRegisterAllSubscribers<T>(T) instead; however that function uses reflection so will be slower than just calling this function once per implementation of ISubscriber.
TryUnregisterAllSubscribers<T>(T)
Removes the given subscriber from the message bus's handlers list. Particularly when a subscriber is intended to have a shorter lifetime than the MessageBus object it subscribed with, handlers MUST be removed when disposed of so they can be garbage collected -- an object cannot be garbage-collected so long as it is registered as a subscriber to a message bus (unless the bus is also being garbage-collected).
Declaration
public bool TryUnregisterAllSubscribers<T>(T subscriber) where T : notnull
Parameters
Type | Name | Description |
---|---|---|
T | subscriber | Subscriber to remove. |
Returns
Type | Description |
---|---|
bool | True if at least one ISubscriber variation implemented by the type passed in was unregistered; false if none of its subscriber types were registered. |
Type Parameters
Name | Description |
---|---|
T | Type of the subscriber. This is typically inferred by the compiler, and really only affects the returned type (for chaining). |
Remarks
This is typically a good (safe) registration method to use by default. However, if you know that your subscriber types will only implement one variation of ISubscriber, or you need unregistration to happen as quickly as possible, then you should instead consider calling TryUnregisterSubscriber<TMessage>(ISubscriber<TMessage>) once for each variation of ISubscriber your subscriber implements. This function uses reflection to figure out what versions of ISubscriber the parameter implements, so can be somewhat slow compared to TryUnregisterSubscriber.
You may call this function even if some of the subscriber's implementations of ISubscriber are not registered with the bus; it will simply unregister the ones that have been registered; and similarly the function will still return true, as long as at least one subscriber was removed. False will only be returned if no ISubscriber implementations were unregistered.
TryUnregisterSubscriber<TMessage>(ISubscriber<TMessage>)
Tries to remove the given subscriber from the message bus's handlers list. Particularly when a subscriber is intended to have a shorter lifetime than the MessageBus object it subscribed with, handlers MUST be removed when disposed of so they can be garbage collected -- an object cannot be garbage-collected so long as it is registered as a subscriber to a message bus (unless the bus is also being garbage-collected).
Declaration
public bool TryUnregisterSubscriber<TMessage>(ISubscriber<TMessage> subscriber)
Parameters
Type | Name | Description |
---|---|---|
ISubscriber<TMessage> | subscriber | Subscriber to remove. |
Returns
Type | Description |
---|---|
bool | True if the subscriber was successfully removed; false if it was never registered. |
Type Parameters
Name | Description |
---|---|
TMessage | Type of message the subscriber is handling. This can typically be inferred by the compiler, barring the case detailed in the ISubscriber<TMessage> remarks where one class subscribes to multiple message types. |
UnregisterAllSubscribers<T>(T)
Removes the given subscriber from the message bus's handlers list. Particularly when a subscriber is intended to have a shorter lifetime than the MessageBus object it subscribed with, handlers MUST be removed when disposed of so they can be garbage collected -- an object cannot be garbage-collected so long as it is registered as a subscriber to a message bus (unless the bus is also being garbage-collected).
Declaration
public void UnregisterAllSubscribers<T>(T subscriber) where T : notnull
Parameters
Type | Name | Description |
---|---|---|
T | subscriber | Subscriber to remove. |
Type Parameters
Name | Description |
---|---|
T | Type of the subscriber. This is typically inferred by the compiler, and really only affects the returned type (for chaining). |
Remarks
This is typically a good (safe) registration method to use by default. However, if you know that your subscriber types will only implement one variation of ISubscriber, or you need unregistration to happen as quickly as possible, then you should instead consider calling UnregisterSubscriber<TMessage>(ISubscriber<TMessage>) once for each variation of ISubscriber your subscriber implements. This function uses reflection to figure out what versions of ISubscriber the parameter implements, so can be somewhat slow compared to UnregisterSubscriber.
You may call this function even if some of the subscriber's implementations of ISubscriber are not registered with the bus; it will simply unregister the ones that have been registered. An exception will be thrown if no implementations of ISubscriber were registered, however.
UnregisterSubscriber<TMessage>(ISubscriber<TMessage>)
Removes the given subscriber from the message bus's handlers list. Particularly when a subscriber is intended to have a shorter lifetime than the MessageBus object it subscribed with, handlers MUST be removed when disposed of so they can be garbage collected -- an object cannot be garbage-collected so long as it is registered as a subscriber to a message bus (unless the bus is also being garbage-collected).
Declaration
public void UnregisterSubscriber<TMessage>(ISubscriber<TMessage> subscriber)
Parameters
Type | Name | Description |
---|---|---|
ISubscriber<TMessage> | subscriber | Subscriber to remove. |
Type Parameters
Name | Description |
---|---|
TMessage | Type of message the subscriber is handling. This can typically be inferred by the compiler, barring the case detailed in the ISubscriber<TMessage> remarks where one class subscribes to multiple message types. |