Struct lunatic::Process

pub struct Process<M, S = Bincode> { /* private fields */ }

Processes are isolated units of compute.

In lunatic, all code runs inside processes. Processes run concurrently and communicate via message passing.

Lunatic’s processes should not be confused with operating system processes. Processes in lunatic are extremely lightweight in terms of memory and CPU (even compared to threads as used in many other programming languages). Because of this, it is not uncommon to have tens or even hundreds of thousands of processes running simultaneously.

The Process type allows us to spawn new processes from rust functions. There are two kinds of processes:

1. Mailbox based processes
2. Protocol based processes

They are differentiated by the second argument of the entry function.

Mailbox based processes

A mailbox process takes a Mailbox that can only receive messages of one type.

Example

let child = Process::spawn(1, |capture, mailbox: Mailbox<i32>| {
   assert_eq!(capture, 1);
   assert_eq!(mailbox.receive(), 2);
});

child.send(2);

Processes don’t share any memory and messages sent between them need to be serialized. By default, the Bincode serializer is used, but other serializers that implement the Serializer trait can be used instead. The serializer just needs to be added to the Mailbox type (e.g. Mailbox<i32, MessagePack>).

Processes can also be linked together using the spawn_link function. This means that if one of them fails (panics) the other will be killed too. It is always recommended to spawn linked processes when they depend on each other. That way we can avoid one process forever waiting on a message from another process that doesn’t exist anymore.

Protocol based processes

A protocol process takes a Protocol that can define a sequence of messages that will be exchanged between two processes. This is also known as a session type. The child will get a reference to the protocol and the parent will get a reference to the opposite protocol.

Example

type AddProtocol = Recv<i32, Recv<i32, Send<i32, End>>>;
let child = Process::spawn(1, |capture: i32, protocol: Protocol<AddProtocol>| {
    assert_eq!(capture, 1);
    let (protocol, a) = protocol.receive();
    let (protocol, b) = protocol.receive();
    let _ = protocol.send(capture + a + b);
});

let child = child.send(2);
let child = child.send(2);
let (_, result) = child.receive();
assert_eq!(result, 5);

The rust type system guarantees that the all messages are sent in the correct order and are of correct type. Code that doesn’t follow the protocol would not compile.

Same as the mailbox, the protocol based process can choose another serializer (e.g. Protocol<AddProtocol, MessagePack>).

If a protocol based process is dropped before the End state is reached, the drop will panic.

Implementations

impl<M, S> Process<M, S>

pub fn new(node_id: u64, process_id: u64) -> Self

pub fn this() -> Self

pub fn spawn<C, T>(capture: C, entry: fn(_: C, _: T)) -> T::Process where
    S: Serializer<C> + Serializer<ProtocolCapture<C>>,
    T: IntoProcess<M, S>,
    T: NoLink, 

Spawn a process.

pub fn spawn_node<C, T>(
    node_id: u64,
    capture: C,
    entry: fn(_: C, _: T)
) -> T::Process where
    S: Serializer<C> + Serializer<ProtocolCapture<C>>,
    T: IntoProcess<M, S>,
    T: NoLink, 

Spawn a process on a remote node.

pub fn spawn_node_config<C, T>(
    node_id: u64,
    config: &ProcessConfig,
    capture: C,
    entry: fn(_: C, _: T)
) -> T::Process where
    S: Serializer<C> + Serializer<ProtocolCapture<C>>,
    T: IntoProcess<M, S>,
    T: NoLink, 

Spawn a process on a remote node.

pub fn spawn_link<C, T>(capture: C, entry: fn(_: C, _: T)) -> T::Process where
    S: Serializer<C> + Serializer<ProtocolCapture<C>>,
    T: IntoProcess<M, S>, 

Spawn a linked process.

pub fn spawn_link_tag<C, T>(
    capture: C,
    tag: Tag,
    entry: fn(_: C, _: T)
) -> T::Process where
    S: Serializer<C> + Serializer<ProtocolCapture<C>>,
    T: IntoProcess<M, S>, 

Spawn a linked process with a tag.

Allows the caller to provide a tag for the link.

pub fn spawn_config<C, T>(
    config: &ProcessConfig,
    capture: C,
    entry: fn(_: C, _: T)
) -> T::Process where
    S: Serializer<C> + Serializer<ProtocolCapture<C>>,
    T: IntoProcess<M, S>,
    T: NoLink, 

Spawn a process with a custom configuration.

pub fn spawn_link_config<C, T>(
    config: &ProcessConfig,
    capture: C,
    entry: fn(_: C, _: T)
) -> T::Process where
    S: Serializer<C> + Serializer<ProtocolCapture<C>>,
    T: IntoProcess<M, S>, 

Spawn a linked process with a custom configuration.

pub fn spawn_link_config_tag<C, T>(
    config: &ProcessConfig,
    capture: C,
    tag: Tag,
    entry: fn(_: C, _: T)
) -> T::Process where
    S: Serializer<C> + Serializer<ProtocolCapture<C>>,
    T: IntoProcess<M, S>, 

Spawn a linked process with a custom configuration & provide tag for linking.

pub fn id(&self) -> u64

Returns a local node process ID.

pub fn node_id(&self) -> u64

Returns a node ID.

pub fn link(&self)

Link process to the one currently running.

pub fn unlink(&self)

Unlink processes from the caller.

pub fn kill(&self)

Kill this process

pub fn register(&self, name: &str)

Register process under a name.

pub fn lookup(name: &str) -> Option<Self>

Look up a process.

impl<M, S> Process<M, S> where
    S: Serializer<M>, 

pub fn send(&self, message: M)

Send a message to the process.

Panics

This function will panic if the received message can’t be serialized into M with serializer S.

pub fn send_after(&self, message: M, duration: Duration) -> TimerRef

Send a message to the process after the specified duration has passed.

Panics

This function will panic if the received message can’t be serialized into M with serializer S.

pub fn tag_send(&self, tag: Tag, message: M)

Send message to process with a specific tag.

Panics

This function will panic if the received message can’t be serialized into M with serializer S.

Trait Implementations

impl<M, S> Clone for Process<M, S>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<M, S> Debug for Process<M, S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, M, S> Deserialize<'de> for Process<M, S>

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<M, S> Hash for Process<M, S>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<M, S> PartialEq<Process<M, S>> for Process<M, S>

Processes are equal if their process id and node id are equal.

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<M, S> Serialize for Process<M, S>

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl<M, S> Eq for Process<M, S>

Proccess equality comparison is an equivalance relation