Crate nuts

Nuts is a library that offers a simple publish-subscribe API, featuring decoupled creation of the publisher and the subscriber.

Quick first example

struct Activity;
let activity = nuts::new_activity(Activity);
activity.subscribe(
    |_activity, n: &usize|
    println!("Subscriber received {}", n)
);
nuts::publish(17usize);
// "Subscriber received 17" is printed
nuts::publish(289usize);
// "Subscriber received 289" is printed

As you can see in the example above, no explicit channel between publisher and subscriber is necessary. The call to publish is a static method that requires no state from the user. The connection between them is implicit because both use usize as message type.

Nuts enables this simple API by managing all necessary state in thread-local storage. This is particularly useful when targeting the web. However, Nuts can be used on other platforms, too. In fact, Nuts has no dependencies aside from std.

Macros

domain_enum

Implements DomainEnumeration for an enum.

Structs

ActivityId

Handle to an Activity that has been registered, with a type parameter to track the activity’s type. Can be used to add type-checked closures to the activity, which will be used as event listeners.

DefaultDomain

If only one domain is required, this can be used. But if you have your own domain type defined with domain_enum! or implementing DomainEnumeration manually, do not use this. Different domain types should never be mixed!

DomainState

Stores passive data that can be accessed in event handlers of multiple activities.

SubscriptionFilter

Defines under which circumstances a subscribing activity should be called. At the moment, the only filter option is to check the activity lifecycle state. The default filter will ignore events when the activity is inactive.

UncheckedActivityId

Pointer to an activity that has been registered. Can be used to set the lifecycle stats of activities.

Enums

LifecycleStatus

Each activity has a lifecycle status that can be changed using set_status. It starts with LifecycleStatus::Active. In the current version of Nuts, the only other status is LifecycleStatus::Inactive.

Traits

Activity

Activities are at the core of Nuts. From the globally managed data, they represent the active part, i.e. they can have event listeners. The passive counter-part is defined by DomainState.

DomainEnumeration

Used for mapping domain identifiers to unique integers. Can be derived with domain_enum!(TYPE);

Functions

new_activity

Consumes a struct and registers it as an Activity.

new_domained_activity

Consumes a struct that is registered as an Activity that has access to the specified domain. Use the returned ActivityId to register callbacks on the activity.

panic_info

Read some information about currently processing activities. This should be called inside a panic hook.

publish

Send the message to all subscribed activities

publish_awaiting_response

Returns a future of type NutsResponse which will resolve after the message has been published and all subscribers have finished processing it.

send_to

Publish a message to a specific activity. The same as id.private_message() but works without an ActivityId.

store_to_domain

Puts the data object to the domain, which can be accessed by all associated activities.