interthread

"The basic idea behind an actor is to spawn a self-contained task that performs some job independently of other parts of the program. Typically these actors communicate with the rest of the program through the use of message passing channels. Since each actor runs independently, programs designed using them are naturally parallel."

• Alice Ryhl

For a comprehensive understanding of the underlying concepts and implementation details of the Actor Model,
it's recommended to read the article Actors with Tokio by Alice Ryhl ( also known as Darksonn ). This article not only inspired the development of the interthread crate but also serves as foundation for the Actor Model implementation logic in it.

What is the problem ?

To achieve parallel execution of individual objects within the same program, it is challenging due to the need for various types that are capable of working across threads. The main difficulty lies in the fact that as you introduce thread-related types, you can quickly lose sight of the main program idea as the focus shifts to managing thread-related concerns. It involves using constructs like threads, locks, channels, and other synchronization primitives. These additional types and mechanisms introduce complexity and can obscure the core logic of the program.

Moreover, existing libraries like actix, axiom, designed to simplify working within the Actor Model, often employ specific concepts, vocabulary, traits and types that may be unfamiliar to users who are less experienced with asynchronous programming and futures.

Solution

The actor macro - when applied to the implementation block of a given "MyActor" object, generates additional types and functions that enable communication between threads.

A notable outcome of applying this macro is the creation of the MyActorLive struct ("ActorName" + "Live"), which acts as an interface/handle to the MyActor object. MyActorLive retains the exact same public method signatures as MyActor, allowing users to interact with the actor as if they were directly working with the original object.

Examples

Filename: Cargo.toml

[dependencies]
interthread = "1.0.0"
oneshot     = "0.1.5" 

Filename: main.rs

pub struct MyActor {
    value: i8,
}

#[interthread::actor(channel=2)] // <-  this is it 
impl MyActor {

    pub fn new( v: i8 ) -> Self {
       Self { value: v } 
    }
    pub fn increment(&mut self) {
        self.value += 1;
    }
    pub fn add_number(&mut self, num: i8) -> i8 {
        self.value += num;
        self.value
    }
    pub fn get_value(&self) -> i8 {
        self.value
    }
}

// uncomment to see the generated code
//#[interthread::example(path="src/main.rs")] 
fn main() {

    let actor = MyActorLive::new(5);

    let mut actor_a = actor.clone();
    let mut actor_b = actor.clone();

    let handle_a = std::thread::spawn( move || { 
    actor_a.increment();
    });

    let handle_b = std::thread::spawn( move || {
    actor_b.add_number(5)
    });

    let _  = handle_a.join();
    let hb = handle_b.join().unwrap();

    // we never know which thread will
    // be first to call the actor so
    // hb = 10 or 11
    assert!(hb >= 10);

    assert_eq!(actor.get_value(), 11);
}

An essential point to highlight is that when invoking MyActorLive::new, not only does it return an instance of MyActorLive, but it also spawns a new thread that contains an instance of MyActor in it. This introduces parallelism to the program.

The code generated by actor takes care of the underlying message routing and synchronization, allowing developers to rapidly prototype their application's core functionality. This fast sketching capability is particularly useful when exploring different design options, experimenting with concurrency models, or implementing proof-of-concept systems. Not to mention, the cases where the importance of the program lies in the result of its work rather than its execution.

The same example can be run in tokio, async-std, and smol, with the only difference being that the methods will be marked as async and need to be awaited for asynchronous execution.

Examples

Filename: Cargo.toml

[dependencies]
interthread = "1.0.0"
tokio = { version="1.28.2",features=["full"]}

Filename: main.rs

pub struct MyActor {
    value: i8,
}

#[interthread::actor(channel=2,lib="tokio")] // <-  one line )
impl MyActor {

    pub fn new( v: i8 ) -> Self {
       Self { value: v } 
    }
    // if the "lib" is defined
    // object methods can be "async" 
    pub async fn increment(&mut self) {
        self.value += 1;
    }
    pub fn add_number(&mut self, num: i8) -> i8 {
        self.value += num;
        self.value
    }
    pub fn get_value(&self) -> i8 {
        self.value
    }
}

#[tokio::main]
async fn main() {

    let actor = MyActorLive::new(5);

    let mut actor_a = actor.clone();
    let mut actor_b = actor.clone();

    let handle_a = tokio::spawn( async move { 
    actor_a.increment().await;
    });

    let handle_b = tokio::spawn( async move {
    actor_b.add_number(5).await
    });

    let _  = handle_a.await;
    let hb = handle_b.await.unwrap();

    // hb = 10 or 11
    assert!(hb >= 10);

    assert_eq!(actor.get_value().await, 11);
}

The actor macro is applied to an impl block, allowing it to be used with both structs and enums to create actor implementations.

Examples

Filename: Cargo.toml

[dependencies]
interthread = "1.0.0"
oneshot     = "0.1.5" 

Filename: main.rs

#[derive(Debug)]
pub struct Dog(String);

impl Dog {
    fn say(&self) -> String {
        format!("{} says: Woof!", self.0)
    }
}

#[derive(Debug)]
pub struct Cat(String);

impl Cat {
    fn say(&self) -> String {
        format!("{} says: Meow!", self.0)
    }
}

#[derive(Debug)]
pub enum Pet {
    Dog(Dog),
    Cat(Cat),
}


#[interthread::actor(channel=2)]
impl Pet {
    // not in this case, but if 
    // the types used with `Pet` have different
    // parameters for the `new` method, 
    // simply pass a ready `Self` type
    // like this
    pub fn new( pet: Self) -> Self {
        pet
    }

    pub fn speak(&self) -> String {
        match self {
           Self::Dog(dog) => {
            format!("Dog {}",dog.say())
            },
           Self::Cat(cat) => {
            format!("Cat {}", cat.say())
            },
        }
    }
    pub fn swap(&mut self, pet: Self ) -> Self {
        std::mem::replace(self,pet)
    }
}


fn main() {

    let pet = PetLive::new( 
        Pet::Dog(Dog("Tango".to_string()))
    );

    let mut pet_a = pet.clone();
    let pet_b     = pet.clone();
    
    let handle_a = std::thread::spawn( move || {
        println!("Thread A - {}",pet_a.speak());
        // swap the the pet and return it  
        pet_a.swap(Pet::Cat(Cat("Kiki".to_string())))
    });

    let swapped_pet = handle_a.join().unwrap();

    let _handle_b = std::thread::spawn( move || {
        println!("Thread B - {}",pet_b.speak());
    }).join();

    //play with both pets now  
    println!("Thread MAIN - {}",pet.speak());
    println!("Thread MAIN - {}",swapped_pet.speak());

}

Outputs

Thread A - Dog Tango says: Woof!
Thread B - Cat Kiki says: Meow!
Thread MAIN - Cat Kiki says: Meow!
Thread MAIN - Dog Tango says: Woof!

The crate also includes a powerful macro called example that can expand the actor macro, ensuring that users always have the opportunity to visualize and interact with the generated code. Which makes actor 100% transparent macro .

For more details, read the

Happy coding!