README_TEMPLATE.md

Nuts

@DOC CRATE

State of Library

With the release of Nuts version 0.2 on crates.io, it has reached an important milestone. The single-threaded features have all been implemented. Maybe a method here and there needs to be added. But I would not expect to go through major API overhauls again in the existing interface at this point.

There is one big pending feature left, however. This is parallel dispatch, covered in #2. Ideally, that would be implemented under the hood. But likely it will make sense to add some more methods to the API.

If and when parallel dispatch get implemented, Nuts probably looks at a stable 1.0 release.

Activities

@DOC ACTIVITY

Publish

@DOC PUBLISH

Subscribe

Activities can subscribe to messages, based on the Rust type identifier of the message. Closures or function pointers can be used to create a subscription for a specific type of messages.

Nuts uses core::any::TypeId internally to compare the types. Subscriptions are called when the type of a published message matches the message type of the subscription.

There are several different methods for creating new subscriptions. The simplest of them is simply called subscribe(...) and it can be used like this:

@DOC SUBSCRIBE_EXAMPLE

Example: Basic Activity with Publish + Subscribe

@DOC NEW_ACTIVITY

Example: Private Channels

In what I have shown you so far, all messages have been shared reference and it is sent to all listeners that registered to a specific message type. An alternative is to use private channels. A sender can then decide which listening activity will receive the message. In that case, the ownership of the message is given to the listener. @DOC PUBLISH_PRIVATE

Activity Lifecycle

@DOC ACTIVITY_LIFECYCLE

Domains

@DOC DOMAIN

Creating Domains

Nuts creates domains implicitly in the background. The user can simply provide an enum or struct that implements the DomainEnumeration trait. This trait requires only the fn id(&self) -> usize function, which maps every object to a number representing the domain.

Typically, domains are defined by an enum and the DomainEnumeration trait is derived using using domain_enum!.

@DOC DOMAIN_MACRO_EXAMPLE

Using Domains

The function nuts::store_to_domain allows to initialize data in a domain. Afterwards, the data is available in subscription functions of the activities.

@DOC DOMAIN_STORE

If activities are associated with a domain, they must be registered using the nuts::new_domained_activity. This will allow to subscribe with closures that have access to domain state. subscribe_domained is used to add those subscriptions. subscribe can still be used for subscriptions that do not access the domain.

Example of Activity with Domain

@DOC NEW_ACTIVITY_WITH_DOMAIN

Advanced: Understanding the Execution Order

@DOC PUBLISH_ADVANCED

Full Demo Examples

A simple example using nuts to build a basic clicker game is available in examples/clicker-game. It requires wasm-pack installed and npm. To run the example, execute wasm-pack build and then cd www; npm install; npm run start. This example only shows minimal features of nuts.

Right now, there are no more examples (some had to be removed due to outdated dependencies). Hopefully that will change at some point.

All examples are set up as their own project. (To avoid polluting the libraries dependencies.) Therefore the standard cargo run --example will not work. One has to go to the example's directory and build it from there.