Class EventBus

Namespace

KeenEyes.Events

Assembly

KeenEyes.Core.dll

A generic event bus for publishing and subscribing to typed events.

public sealed class EventBus

Inheritance

object

EventBus

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Define a custom event
public readonly record struct DamageEvent(Entity Target, int Amount);

// Subscribe to the event
var subscription = world.Events.Subscribe<DamageEvent>(e =>
{
    Console.WriteLine($"Entity {e.Target} took {e.Amount} damage");
});

// Publish an event
world.Events.Publish(new DamageEvent(entity, 50));

// Unsubscribe when done
subscription.Dispose();

Remarks

The event bus provides a decoupled messaging system where publishers and subscribers don't need direct references to each other. Events are dispatched synchronously to all registered handlers in registration order.

Each event type has its own list of subscribers. When an event is published, only handlers registered for that specific type are invoked.

Performance note: When no handlers are registered for an event type, publishing that event has minimal overhead (a dictionary lookup that returns false).

Methods

GetHandlerCount<T>()

Gets the number of handlers registered for a specific event type.

public int GetHandlerCount<T>()

Returns

int

The number of registered handlers for the event type.

Type Parameters

T

The event type to check.

Remarks

This method is primarily useful for testing and debugging.

HasHandlers<T>()

Checks if there are any handlers registered for a specific event type.

public bool HasHandlers<T>()

Returns

bool

true if at least one handler is registered; otherwise, false.

Type Parameters

T

The event type to check.

Examples

// Skip creating expensive event data if no one is listening
if (eventBus.HasHandlers<ExpensiveEvent>())
{
    var eventData = CreateExpensiveEventData();
    eventBus.Publish(eventData);
}

Remarks

This can be used to skip expensive event creation when no handlers are listening.

Publish<T>(in T)

Publishes an event to all registered handlers.

public void Publish<T>(in T evt)

Parameters

evt T

The event data to pass to handlers.

Type Parameters

T

The event type to publish.

Examples

eventBus.Publish(new DamageEvent(target, 25));

Remarks

Handlers are invoked synchronously in registration order. If no handlers are registered for the event type, this method returns immediately with minimal overhead.

If a handler throws an exception, it will propagate to the caller and subsequent handlers will not be invoked. Consider wrapping handlers in try-catch if you need fault tolerance.

Subscribe<T>(Action<T>)

Subscribes a handler to events of the specified type.

public EventSubscription Subscribe<T>(Action<T> handler)

Parameters

handler Action<T>

The handler to invoke when events of type T are published.

Returns

EventSubscription

An KeenEyes.EventSubscription that can be disposed to unsubscribe the handler.

Type Parameters

T

The event type to subscribe to.

Examples

var subscription = eventBus.Subscribe<GameOverEvent>(e =>
{
    Console.WriteLine($"Game over! Score: {e.FinalScore}");
});

Remarks

Handlers are invoked synchronously in registration order when events are published. If a handler throws an exception, subsequent handlers will not be invoked.

The same handler instance can be registered multiple times, in which case it will be invoked multiple times per event. Each registration returns a separate subscription.

Exceptions

ArgumentNullException

Thrown when handler is null.