Crate generic_event_queue

source ·
Expand description

Provides a generic Event-Queue API.

This module provides a FIFO (First-in, First-out) event system based on the sender / receiver / message channel model found in std::sync::mpsc.

Examples

All event queues use the same API, so the following examples should work for any type implementing the Event-Queue traits.

Create an Event Queue

let (event_sender, event_receiver) = mpsc::event_queue();

Handling Events

An EventReceiver will collect incoming events, and store them until they are ready to be processed. The order of incoming events is always preserved.

Queued events are queried in a loop. Querying events requires you have mutable access to the Event Queue.

while let Some(event) = event_receiver.next_event() {
    match event {
        EventType::Event => (), // Handle the event.
    }
}

Sending Events

To send an event to an EventReceiver, we use an EventSender. An event sender is like a tunnel, through which you can send data, and it will pop out on the other side.

event_sender.send_event(EventType::Event);

Cloning, and Transferring Ownership of an EventSender

Event Senders are extremely useful because they can be freely, and safely cloned, and their ownership moved to other code that needs to send events. This enables sending events from code that otherwise does not have access to the Event Queue.

// The EventSender can be cloned, and freely passed around.
let other_type = SomeOtherType::new(event_sender.clone());
some_other_function(&event_sender);

// The original EventSender is unaffected.
event_sender.send_event(EventType::Event);

Sending an EventSender to Another Thread

Event Senders can be safely sent to other threads.

// This EventSender stays on the main thread with the EventReceiver.
event_sender.send_event(EventType::Event);

// The clone is moved to the other thread.
let thread_sender = event_sender.clone();
std::thread::spawn(move || {
    thread_sender.send_event(EventType::Event);
}).join();

Modules

  • mpsc
    Provides a Multi-Producer, Single-Consumer Event-Queue implementation.

Structs

Traits