Crate dfqueue

source ·
Expand description

DFQ is a decoupled, fault-tolerant, multi-producer single-consumer queue. DFQ is compatible with no_std and is interrupt-safe by being entirely lock-free and mostly wait-free.

DFQ accepts immutable data items only and does not allow the consumer to immediately remove (pop) or modify the items in the queue. In a transactional fashion, the consumer must call mark_completed on a queued item to indicate that that item can be safely removed from the queue. Because the original producer that enqueued that item retains a reference to that item, it is then safe for any entity (any producer or the consumer) to remove it from the queue. Currently, the consumer simply removes completed items from the queue on the next occasion of a conumser method like peek().

Each producer retains ownership of the data items it queues, and only those items. Thus, a producer is able to query the status of that item’s handling by the consumer, to see if it is still on the queue or if something has gone wrong and it has failed. If a failure has occurred, that producer can enqueue that item again, but of course its original position in the queue will be lost.

Modules

  • mpsc_queue
    Ported from Rust’s std::sync::mpsc::Queue.

Structs

  • DFQueue
    The actual queue, an opaque type that cannot be used directly. The user must use DFQueueConsumer and DFQueueProducer.
  • DFQueueConsumer
    A consumer that can process (peek into) elements in a DFQueue, but not actually remove them. Do not wrap this in an Arc or Mutex, the queue it is already protected by those on the interior.
  • DFQueueProducer
    A producer that can enqueue elements into a DFQueue. Do not wrap this in an Arc or Mutex, the queue it is already protected by those on the interior.
  • PeekedData
    A wrapper around data in the queue that allows a DFQueueConsumer to access the data and mark the queued item as completed. Automatically Derefs to the inner type &T, just like Arc does.
  • QueuedData
    A special reference type that wraps a data item that has been queued. This is returned to a producer thread (the user of a DFQueueProducer) when enqueuing an item onto the queue so that the producer can retain a reference to it in the case of failure.

Enums