Darp.Utils.Messaging 1.19.2

<div align="center">

Darp.Utils.Messaging

A source generator to generate implementation for MessageSource and MessageSinks.

</div>

You should use this packet if you

• want events that can be subscribed to by a specific type
• require support for ref-like messages (>= net9.0)
• want a very slim library
• have a few, long-living subscribers with a high message throughput
• have a lot of different message types

This package is not for you if you

• need async handling
• do not want source generation
• additional features
• have thousands of subscribers at once that are not expecting an event

Usage

The library is structured in two core roles:

• MessageSource: A class which holds a list of subscribers that can be notified about a new message
• MessageSink: A class which holds one or multiple handlers for specific message types

This library generates necessary boilerplate for those two roles and provides a few additional helpers.

MessageSource

A message source can be defined by adding the MessageSource attribute to a partial class. The source generator will generate a list of subscribers, a Subscribe method as well as a protected Publish method which can be used to notify subscribers about a new value

using Darp.Utils.Messaging;

[MessageSource]
public sealed partial class TestMessageSource
{
    public void PublishInt()
    {
        PublishMessage(42);
    }
}

MessageSink

A message sink can be defined by adding a MessageSink attribute to any void method with only a single parameter. The source generator will generate a class which can be used to subscribe to any source and links the chosen method to those events.

using Darp.Utils.Messaging;

public sealed partial class TestMessageSink
{
    [MessageSink]
    private void OnInt(int message) => Console.WriteLine($"Received '{message}'");

    [MessageSink]
    private void OnSpan(System.ReadOnlySpan<byte> message) { }

    // Handle any message that was not handled by any other method
    [MessageSink]
    private void OnAny<T>(T message) where T : allows ref struct { } // Add 'allows ref struct' only for >= net9.0
}

This sink can now be subscribed to the previously defined source.

var source = new TestMessageSource();
source.Subscribe(new TestMessageSink());
source.PublishInt();
// Output: Received '42'

Helpers

A few helpers are predefined in the library. If you do not want to define a new class you can use the MessageSubject. Also, it is possible to Subscribe for a certain type directly or convert the source to an IObservable:

using Darp.Utils.Messaging;

var subject = new MessageSubject();

// Subscribe to any source and use the dispose method to unsubscribe
IDisposable disposable = source.Subscribe<int>(_ => {});
source.Subscribe<string>(_ => {});

// Convert to an IObservable and use with reactive overloads
IObservable observable = source.AsObservable<int>();

// Publish new values
subject.Publish("Some string");
subject.Publish(42);

You can take a look at the tests at test/Darp.Utils.Messaging.Generator.Verify for additional usage examples. Also, you can take a look at the expected generated code there.

TODO

• DisposableBags
• Analyzers
• Evaluate filters
• Return bool/int whether publish was handled