Crate ector

source ·
Expand description

Ector is an open source async, no-alloc actor framework for embedded devices.

CI crates.io docs.rs Matrix

Ector is an open source async, no-alloc actor framework for embedded devices. It integrates with embassy, the embedded async project.

Actor System

An actor system is a framework that allows for isolating state within narrow contexts, making it easier to reason about system. Within a actor system, the primary component is an Actor, which represents the boundary of state usage. Each actor has exclusive access to its own state and only communicates with other actors through message-passing.

Example

#![macro_use]
#![feature(generic_associated_types)]
#![feature(type_alias_impl_trait)]

use ector::*;

/// A Counter that we wish to create an Actor for.
pub struct Counter {
    count: u32,
}

// The message our actor will handle.
pub struct Increment;

/// An Actor implements the Actor trait.
impl Actor for Counter {
    /// The Message associated type is the message types that the Actor can receive.
    type Message = Increment;

    /// An actor has to implement the on_mount method. on_mount() is invoked when the internals of an actor is ready,
    /// and the actor can begin to receive messages from an inbox.
    ///
    /// The following arguments are provided:
    /// * The address to 'self'
    /// * An inbox from which the actor can receive messages
    async fn on_mount<M>(&mut self, _: Address<Self::Message<'m>>, mut inbox: M) -> !
        where M: Inbox<Self::Message<'m>> {
    {
        loop {
            // Await the next message and increment the counter
            let _ = inbox.next().await;
            self.count += 1;
        }
    }
}

 /// The entry point of the application is using the embassy runtime.
 #[embassy::main]
 async fn main(spawner: embassy::executor::Spawner) {

     // Mounting the Actor will spawn an embassy task
     let addr = ector::actor!(spawner, counter, Counter, Counter { count  0 });

     // The actor address may be used in any embassy task to communicate with the actor.
     let _ = addr.notify(Increment).await;
 }

Building

To build ector, you must install the nightly rust toolchain. Once installed, you can build and test the framework by running

cargo test

Directory layout

  • ector - an actor framework
  • macros - macros used by drogue-device and application code

Contributing

See the document CONTRIBUTING.md.

Community

Modules

Macros

  • actor
    Spawn an actor given a spawner and the actors name, type and instance.
  • spawn_context
    Spawn an ActorContext for a given spawner

Structs

  • ActorContext
    A context for an actor, providing signal and message queue. The QUEUE_SIZE parameter is a const generic parameter, and controls how many messages an Actor can handle.
  • Request

Traits

  • Actor
    Trait that each actor must implement. An actor defines a message type that it acts on, and an implementation of on_mount which is invoked when the actor is started.
  • ActorAddress
    A trait send message to another actor.
  • ActorRequest
  • Inbox

Type Aliases