Crate calloop

Calloop, a Callback-based Event Loop

This crate provides an EventLoop type, which is a small abstraction over a polling system. The main difference between this crate and other traditional rust event loops is that it is based on callbacks: you can register several event sources, each being associated with a callback closure that will be invoked whenever the associated event source generates events.

The main target use of this event loop is thus for apps that expect to spend most of their time waiting for events and wishes to do so in a cheap and convenient way. It is not meant for large scale high performance IO.

How to use it

extern crate calloop;

use calloop::{generic::Generic, EventLoop, Interest, Mode};

use std::time::Duration;

fn main() {
    // Create the event loop
    let mut event_loop = EventLoop::try_new()
                .expect("Failed to initialize the event loop!");
    // Retrieve an handle. It is used to insert new sources into the event loop
    // It can be cloned, allowing you to insert sources from within source callbacks
    let handle = event_loop.handle();

    // Inserting an event source takes this general form
    // it can also be done from within the callback of an other event source
    handle.insert_source(
        // a type implementing the EventSource trait
        source,
        // a callback that is invoked whenever this source generates an event
        |event, metadata, shared_data| {
            // This callback is given 3 values:
            // - the event generated by the source
            // - &mut access to some metadata, specific to the event source
            // - &mut access to the global shared data that was passed to EventLoop::dispatch
        }
    );

    // Actual run of your loop
    //
    // Dispatch received events to their callbacks, waiting at most 20 ms for
    // new events between each invocation of the provided callback.
    //
    // The `&mut shared_data` is a mutable reference that will be forwarded to all
    // your callbacks, allowing them to share some state
    event_loop.run(Duration::from_millis(20), &mut shared_data, |shared_data| {
        /*
        * Insert here the processing you need to do do between each waiting session
        * like your drawing logic if you're doing a GUI app for example.
        */
    });
}

Event source types

The event loop is backed by an OS provided polling selector (epoll on Linux).

This crate also provide some adapters for common event sources such as:

• MPSC channels
• Timers
• unix signals on Linux

As well as generic objects backed by file descriptors.

It is also possible to insert "idle" callbacks. These callbacks represent computations that need to be done at some point, but are not as urgent as processing the events. These callbacks are stored and then executed during EventLoop::dispatch, once all events from the sources have been processed.

Async/Await compatibility

calloop can be used with futures, both as an executor and for monitoring Async IO.

Activating the executor cargo feature will add the futures module, which provides a future executor that can be inserted into an EventLoop as yet another EventSource.

IO objects can be made Async-aware via the LoopHandle::adapt_io method. Waking up the futures using these objects is handled by the associated EventLoop directly.

Custom event sources

You can create custom event sources can will be inserted in the event loop by implementing the EventSource trait. This can be done either directly from the file descriptors of your source of interest, or by wrapping an other event source and further processing its events. An EventSource can register more than one file descriptor and aggregate them.

Platforms support

Currently, only Linux and the *BSD are supported.

Modules

channel	An MPSC channel whose receiving end is an event source
futures	A futures executor as an event source
generic	A generic event source wrapping an IO objects or file descriptor
io	Adapters for async IO objects
ping	Ping to the event loop
signals	Event source for tracking Unix signals
timer	Timer-based event sources

Structs

Dispatcher	An event source with its callback.
EventLoop	An event loop
Idle	An idle callback that was inserted in this loop
InsertError	An error generated when trying to insert an event source
Interest	Interest to register regarding the file descriptor
LoopHandle	An handle to an event loop
LoopSignal	A signal that can be shared between thread to stop or wakeup a running event loop
Poll	The polling system
Readiness	Readiness for a file descriptor notification
RegistrationToken	A token representing a registration in the EventLoop.
Token	A token (for implementation of the EventSource trait)

Enums

Mode	Possible modes for registering a file descriptor

Traits

EventSource

Trait representing an event source