Struct stakker::PipedThread

pub struct PipedThread<O: Send + Sync + 'static, I: Send + Sync + 'static> { /* fields omitted */ }

A thread connected to the actor runtime via channels

This takes care of starting a thread and transferring data to and from it via channels. Data sent to the thread has type O, and data received has type I. These would often be enums to handle different kinds of data (e.g. messages, commands or responses as required).

This is useful for offloading synchronous or blocking work to another thread. So the normal pattern of use would be for the thread to block on PipedLink::recv until it gets something to process. Processing could involve sending messages on other channels or streams and waiting for replies, or running data in parallel through a thread pool. Processing the received message might or might not result in a message to send back with PipedLink::send. Another use could be for blocking input, where the thread waits on a device, and uses PipedLink::send to pass back received data.

The only thing that this thread can't do is wait for both PipedLink::recv and some other input at the same time. If you need that, for now you'll need to write your own interface code to crossbeam or some other channel library, using Waker to interface back to Stakker.

Cleanup is handled as follows:

• If the thread terminates normally or panics, then the underlying Waker notifies the main thread and fwd_term is called with the panic error, or None if there was no panic. This handler can discard the PipedThread instance to complete the cleanup, and start a new thread if necessary.

• If the PipedThread instance is dropped in the main thread, then a cancel flag is set which the thread will notice next time it tries to send or receive data. The thread should then terminate. So if the PipedThread instance is kept within the same actor that is handling the incoming data, then this takes care of thread cleanup automatically if the actor fails unexpectedly.

Implementations

impl<O: Send + Sync + 'static, I: Send + Sync + 'static> PipedThread<O, I>

pub fn spawn(
    fwd_recv: Fwd<I>,
    fwd_term: Fwd<Option<String>>,
    core: &mut Core,
    run: impl FnOnce(&mut PipedLink<O, I>) + Send + 'static
) -> Self

Spawn a new thread. fwd_recv will be called for each incoming message. fwd_term will be called when the thread terminates with the argument of None for normal termination, or Some(msg) for a panic. The run argument is the closure that will be run within the new thread. The PipedLink argument passed to it allows the new thread to send and receive messages.

Note: core argument is third argument so that fwd_to! and similar macros can be used directly in the call arguments, without borrow errors.

pub fn send(&mut self, msg: O)

Send a message to the thread. If the thread is blocked on receive, wake it.

Trait Implementations

impl<O: Send + Sync + 'static, I: Send + Sync + 'static> Drop for PipedThread<O, I>

fn drop(&mut self)

Executes the destructor for this type.