Struct Mailbox 

pub struct Mailbox<T: 'static> { /* private fields */ }

A mailbox for sending messages to a value owned by a background task.

Mailbox<T> provides thread-safe access to a value of type T by serializing all operations through an async message queue. The value is owned by a background task that processes incoming messages sequentially.

Type Parameters

• T - The type of value contained in the mailbox. Must be 'static to ensure the background task can own it safely.

Thread Safety

The mailbox enables other threads to safely access a value living on another thread without explicit locks. The mailbox handle itself is always Send and Sync, allowing it to be shared across threads. All operations on the value are serialized through an async message queue, providing lock-free concurrent access. When T is not Send, the value remains pinned to its original thread but can still be safely accessed from other threads through the mailbox.

Implementations

impl<T: 'static> Mailbox<T>

pub fn new<E: LocalExecutor>(executor: E, value: T) -> Self

Creates a new mailbox with the given value on the specified executor.

The value will be moved to a background task that processes incoming messages. The executor is consumed to spawn the background task.

Parameters

• executor - The executor to spawn the background task on
• value - The value to be owned by the background task

Examples

use native_executor::{Mailbox, MainExecutor};
use std::collections::HashMap;

let mailbox = Mailbox::new(MainExecutor, HashMap::<String, i32>::new());

pub fn main(value: T) -> Self

Creates a new mailbox with the given value on the main executor.

This is a convenience method equivalent to Mailbox::new(MainExecutor, value). The background task will be spawned on the main executor.

Parameters

• value - The value to be owned by the background task

Examples

use native_executor::Mailbox;
use std::collections::HashMap;

let mailbox = Mailbox::main(HashMap::<String, i32>::new());

pub fn handle(&self, update: impl FnOnce(&T) + Send + 'static)

Sends a non-blocking update to the mailbox value.

The provided closure will be called with a reference to the value in the background task. This operation is non-blocking and will not wait for the update to be processed.

If the background task has been dropped or the channel is full, the update may be silently discarded.

Parameters

• update - A closure that will be called with a reference to the value

Examples

use native_executor::Mailbox;
use std::collections::HashMap;

let mailbox = Mailbox::main(HashMap::<String, i32>::new());

// Send a non-blocking update
mailbox.handle(|map| {
    map.insert("key".to_string(), 42);
});

pub async fn call<R>(&self, f: impl FnOnce(&T) -> R + Send + 'static) -> R

where R: Send + 'static,

Makes an asynchronous call to the mailbox value and returns the result.

The provided closure will be called with a reference to the value in the background task, and the result will be returned to the caller. This operation blocks until the call is processed and the result is available.

Parameters

• f - A closure that will be called with a reference to the value and returns a result

Returns

The result returned by the closure after it has been executed on the value.

Panics

Panics if the background task has been dropped or the channel is closed, making it impossible to receive the result.

Examples

use native_executor::Mailbox;
use std::collections::HashMap;

let mailbox = Mailbox::main(HashMap::<String, i32>::new());

// Make an async call that returns a value
let value = mailbox.call(|map| {
    map.get("key").copied().unwrap_or(0)
}).await;

Trait Implementations

impl<T: Debug + 'static> Debug for Mailbox<T>

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

Formats the value using the given formatter.