Struct tokio::reactor::Reactor

pub struct Reactor { /* fields omitted */ }

The core reactor, or event loop.

The event loop is the main source of blocking in an application which drives all other I/O events and notifications happening. Each event loop can have multiple handles pointing to it, each of which can then be used to create various I/O objects to interact with the event loop in interesting ways.

Methods

impl Reactor

pub fn new() -> Result<Reactor, Error>

Creates a new event loop, returning any error that happened during the creation.

pub fn handle(&self) -> Handle

Returns a handle to this event loop which can be sent across threads and can be used as a proxy to the event loop itself.

Handles are cloneable and clones always refer to the same event loop. This handle is typically passed into functions that create I/O objects to bind them to this event loop.

pub fn set_fallback(&self) -> Result<(), SetFallbackError>

Configures the fallback handle to be returned from Handle::default.

The Handle::default() function will by default lazily spin up a global thread and run a reactor on this global thread. This behavior is not always desirable in all applications, however, and sometimes a different fallback reactor is desired.

This function will attempt to globally alter the return value of Handle::default() to return the handle specified rather than a lazily initialized global thread. If successful then all future calls to Handle::default() which would otherwise fall back to the global thread will instead return a clone of the handle specified.

Errors

This function may not always succeed in configuring the fallback handle. If this function was previously called (or perhaps concurrently called on many threads) only the first invocation of this function will succeed. All other invocations will return an error.

Additionally if the global reactor thread has already been initialized then this function will also return an error. (aka if Handle::default has been called previously in this program).

pub fn turn(&mut self, max_wait: Option<Duration>) -> Result<Turn, Error>

Performs one iteration of the event loop, blocking on waiting for events for at most max_wait (forever if None).

This method is the primary method of running this reactor and processing I/O events that occur. This method executes one iteration of an event loop, blocking at most once waiting for events to happen.

If a max_wait is specified then the method should block no longer than the duration specified, but this shouldn't be used as a super-precise timer but rather a "ballpark approximation"

Return value

This function returns an instance of Turn

Turn as of today has no extra information with it and can be safely discarded. In the future Turn may contain information about what happened while this reactor blocked.

Errors

This function may also return any I/O error which occurs when polling for readiness of I/O objects with the OS. This is quite unlikely to arise and typically mean that things have gone horribly wrong at that point. Currently this is primarily only known to happen for internal bugs to tokio itself.

pub fn is_idle(&self) -> bool

Returns true if the reactor is currently idle.

Idle is defined as all tasks that have been spawned have completed, either successfully or with an error.

pub fn background(self) -> Result<Background, Error>

Run this reactor on a background thread.

This function takes ownership, spawns a new thread, and moves the reactor to this new thread. It then runs the reactor, driving all associated I/O resources, until the Background handle is dropped or explicitly shutdown.

Trait Implementations

impl Debug for Reactor

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

Formats the value using the given formatter.

impl AsRawFd for Reactor

fn as_raw_fd(&self) -> i32

Extracts the raw file descriptor.

impl Park for Reactor

type Unpark = Handle

Unpark handle type for the Park implementation.

type Error = Error

Error returned by park

fn unpark(&self) -> <Reactor as Park>::Unpark

Get a new Unpark handle associated with this Park instance.

fn park(&mut self) -> Result<(), Error>

Block the current thread unless or until the token is available.

fn park_timeout(&mut self, duration: Duration) -> Result<(), Error>

Park the current thread for at most duration.