drogue-iot / ector

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

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

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

• Drogue IoT Matrix Chat Room
• We have bi-weekly calls at 9:00 AM (GMT). Check the calendar to see which week we are having the next call, and feel free to join!
• Drogue IoT Forum
• Drogue IoT YouTube channel
• Follow us on Twitter!

ector's Issues

Potential use after free using ActorRequest

Here you are illegally transmuting a DynamicSender<'a, ...> to DynamicSender<'static, ...>.

ector/ector/src/actor.rs

Lines 77 to 89 in 0505b2f

	impl<'a, M, R> ActorRequest<M, R> for DynamicSender<'a, Request<M, R>> {
	async fn request(&self, message: M) -> R {
	let channel: Channel<NoopRawMutex, R, 1> = Channel::new();
	let sender: DynamicSender<'_, R> = channel.sender().into();
	// We guarantee that channel lives until we've been notified on it, at which
	// point its out of reach for the replier.
	let reply_to = unsafe { core::mem::transmute(&sender) };
	let message = Request::new(message, reply_to);
	self.notify(message).await;
	channel.recv().await
	}
	}

You are not actually guaranteeing that the channel will outlive the sender. It's possible to call the request function with embassy_time::with_timeout or embassy_futures::select, which in turn could cancel the recv's future and drop the channel before the sender is used, resulting in a dangling reference.

To illustrate, I edited the examples/request.rs

async fn test(addr: DynamicAddress<Request<&'static str, &'static str>>) {
    let _ = embassy_time::with_timeout(Duration::from_micros(1), addr.request("Hello")).await;
}

full source code and miri output here

ActorRequest::request is a safe API and it should be impossible to cause UB with it, either mark it as unsafe, or rework it. I'm not actually sure you can do this safely without declaring the channel as static or without dynamic allocation.

Multiple messages types for a single actor

The ector implementation appears to impose a one-to-one mapping between an actor and a given message type. The actix handler trait for example is parameterized to allow a given actor to handle multiple message types. Is the one-to-one mapping by design or could ector be extended to support a single actor handling multiple message types?