Struct Arbiter

Source

pub struct Arbiter(/* private fields */);

Expand description

An asynchronous execution environment running on one OS thread.

Creating an arbiter starts a thread with its own local event loop. Futures spawned on that event loop are not required to implement Send. The system’s primary arbiter instead runs on the thread driving its SystemRunner.

Clones refer to the same arbiter and may be sent to other threads. Use handle to submit Send futures from another thread.

Implementations§

Source §

impl Arbiter

Source

pub fn current() -> Arbiter

Returns the arbiter running on the current thread.

§Panics

Panics if no arbiter is running on the current thread.

Source

pub fn stop(&self)

Requests that the arbiter stop its event loop.

This returns without waiting for shutdown; use join to wait for a spawned arbiter’s thread. To stop the primary arbiter’s event loop, stop its System or complete the future driving the system.

Source

pub fn new() -> Arbiter

Starts an arbiter on a new thread with an automatically generated name.

Uses the current system’s runner and thread configuration.

§Panics

Panics if no current system is installed or the arbiter thread cannot be started.

Source

pub fn with_name(name: String) -> Arbiter

Starts an arbiter on a new thread with the specified name.

Uses the current system’s runner and thread configuration.

§Panics

Panics if no current system is installed or the arbiter thread cannot be started.

Source

pub fn with_init<F>(name: String, init: F) -> Arbiter
where F: FnOnce() + Send + 'static,

Starts an arbiter on a new thread with the specified name.

init runs on the new thread before the arbiter’s runtime is created, for example to set the thread’s CPU affinity, so that the runtime’s memory is allocated on the NUMA node of that CPU. The new thread has no current system or arbiter during init, and its arbiter storage is cleared after init returns.

§Panics

Panics if no current system is installed, the thread cannot be started, or initialization fails, including a panic in init.

Source

pub fn id(&self) -> Id

Returns the arbiter identifier.

Source

pub fn name(&self) -> &str

Returns the arbiter name.

Source

pub fn handle(&self) -> &Handle

Returns a handle to the arbiter’s runtime.

Source

pub fn latency(&self) -> Option<LatencyMetrics>

Returns the arbiter’s scheduling latency.

Returns None if latency sampling is disabled, see Builder::latency_interval.

Source

pub fn is_running(&self) -> bool

Returns whether the arbiter is running.

A stop request does not change this immediately. The flag is cleared after the event loop exits, before on_stop callbacks.

Source

pub fn get_value<T, F>(f: F) -> T
where T: Clone + 'static, F: FnOnce() -> T,

Returns a value from thread-local arbiter storage, inserting it if absent.

Values are keyed by type and shared with get_item, set_item, and with_item on the calling thread. Existing values are cloned. The initializer runs while storage is mutably borrowed and must not reenter these storage APIs.

If the storage has already been destroyed because the thread is exiting, the value returned by f is not stored.

Source

pub fn on_shutdown<F>(f: F)
where F: FnOnce() + 'static,

Registers a callback to run when the current thread’s arbiter shuts down.

Callbacks run once, in registration order, on the arbiter’s thread when its stop is requested, by Arbiter::stop() or System::stop(), while the event loop is still running. An arbiter that ends without a stop request, such as one driven by SystemRunner::block_on(), runs them once its event loop has exited instead. A callback registered by another callback runs in the same shutdown.

If the thread is exiting and its thread-local storage has already been destroyed, f is dropped without running. If f panics after the event loop panicked, the process is aborted.

Source

pub fn on_stop<F>(self, f: F) -> Self
where F: Fn() + Send + Sync + 'static,

Adds a callback to run after the arbiter stops.

The callback runs on the arbiter thread after its event loop exits and its running flag is cleared. Register before shutdown; registration after finalization does not invoke the callback.

If f panics after the event loop panicked, the process is aborted.

Source

pub fn join(&mut self) -> Result<()>

Waits for the arbiter’s thread to stop.

This returns immediately for an arbiter that does not own a thread handle, including the system’s primary arbiter. The join handle is shared by all clones and consumed by the first call. This does not request a stop.