folly::LockFreeRingBuffer

Synopsis

Declared in <folly/concurrency/container/LockFreeRingBuffer.h>

template<
    typename T,
    template<typename> typename Atom = atomic,
    template<typename> typename Storage = RingBufferTrivialStorage>
class LockFreeRingBuffer;

Description

1. Writers cannot block on other writers UNLESS they are <capacity> writes apart from each other (writing to the same slot after a wrap-around) 2. Writers cannot block on readers 3. Readers can wait for writes that haven't occurred yet 4. Readers can detect if they are lagging behind

In this sense, reads from this buffer are best-effort but writes are guaranteed.

Another way to think about this is as an unbounded stream of writes. The buffer contains the last <capacity> writes but readers can attempt to read any part of the stream, even outside this window. The read API takes a Cursor that can point anywhere in this stream of writes. Reads from the "future" can optionally block but reads from the "past" will always fail.

Types

Name	Description
`Cursor`	Opaque pointer to a past or future write. Can be moved relative to its current location but not in absolute terms.

Member Functions

Name	Description
`LockFreeRingBuffer` [constructor]	Constructors
`operator=` [deleted]	Copy assignment is deleted.
`capacity`	Returns the number of writes the buffer retains.
`currentHead`	Returns a Cursor pointing to the first write that has not occurred yet.
`currentTail`	Returns a Cursor pointing to the earliest readable write.
`internalBufferLocation`	Returns the address and length of the internal buffer. Unsafe to inspect this region at runtime. And not useful. Useful when using LockFreeRingBuffer to store data which must be retrieved from a core dump after a crash if the given region is added to the list of dumped memory regions.
`tryRead`	Read the value at the cursor. Returns true if the read succeeded, false otherwise. If the return value is false, dest is to be considered partially read and in an inconsistent state. Readers are advised to discard it.
`waitAndTryRead`	Read the value at the cursor or block if the write has not occurred yet. Returns true if the read succeeded, false otherwise. If the return value is false, dest is to be considered partially read and in an inconsistent state. Readers are advised to discard it.
`write`	Perform a single write of an object of type T. Writes can block iff a previous writer has not yet completed a write for the same slot (before the most recent wrap-around).
`writeAndGetCursor`	Perform a single write of an object of type T. Writes can block iff a previous writer has not yet completed a write for the same slot (before the most recent wrap-around). Returns a Cursor pointing to the just-written T.