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.

Inheritance

object

MessageBus

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Namespace: GoRogue.Messaging

Assembly: GoRogue.dll

Syntax

public class MessageBus

Constructors

MessageBus()

Constructor.

Declaration

public MessageBus()

Properties

SubscriberCount

Number of subscribers currently listening on this message bus.

Declaration

public int SubscriberCount { get; }

Property Value

Type	Description
int

Methods

RegisterAllSubscribers<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.

Extension Methods

Utility.Yield<T>(T)