ReaderWriterQueue Class Reference

#include <readerwriterqueue.h>

Collaboration diagram for ReaderWriterQueue:

Classes
struct	Block

Public Member Functions
AE_NO_TSAN	ReaderWriterQueue (size_t maxSize=15)
AE_NO_TSAN	~ReaderWriterQueue ()
AE_FORCEINLINE bool	enqueue (UINT8 *const &element) AE_NO_TSAN
bool	try_dequeue (UINT8 *&result) AE_NO_TSAN
UINT8 *	peek () AE_NO_TSAN
bool	pop () AE_NO_TSAN
size_t	size_approx () const AE_NO_TSAN

Public Attributes
UINT8 *	value_type

Private Types
enum	AllocationMode { CanAlloc , CannotAlloc }

Private Member Functions
bool	inner_enqueue (AllocationMode canAlloc, UINT8 *const &element) AE_NO_TSAN

Static Private Member Functions
static AE_FORCEINLINE size_t	ceilToPow2 (size_t x)
template<typename U >
static AE_FORCEINLINE UINT8 *	align_for (UINT8 *ptr) AE_NO_TSAN
static Block *	make_block (size_t capacity) AE_NO_TSAN

Private Attributes
weak_atomic< Block * >	frontBlock
char	cachelineFiller [MOODYCAMEL_CACHE_LINE_SIZE - sizeof(weak_atomic< Block * >)]
weak_atomic< Block * >	tailBlock
size_t	largestBlockSize

Detailed Description

Definition at line 52 of file readerwriterqueue.h.

Member Enumeration Documentation

AllocationMode

enum ReaderWriterQueue::AllocationMode

private

Enumerator
CanAlloc
CannotAlloc

Definition at line 379 of file readerwriterqueue.h.

{ CanAlloc, CannotAlloc };

Constructor & Destructor Documentation

ReaderWriterQueue()

AE_NO_TSAN ReaderWriterQueue::ReaderWriterQueue ( size_t  maxSize = 15 )

inlineexplicit

Definition at line 81 of file readerwriterqueue.h.

  {
    assert(maxSize > 0);
    assert(MAX_BLOCK_SIZE == ceilToPow2(MAX_BLOCK_SIZE) && "MAX_BLOCK_SIZE must be a power of 2");
    assert(MAX_BLOCK_SIZE >= 2 && "MAX_BLOCK_SIZE must be at least 2");
    
    Block* firstBlock = nullptr;
    
    largestBlockSize = ceilToPow2(maxSize + 1);   // We need a spare slot to fit maxSize elements in the block
    if (largestBlockSize > MAX_BLOCK_SIZE * 2) {
      // We need a spare block in case the producer is writing to a different block the consumer is reading from, and
      // wants to enqueue the maximum number of elements. We also need a spare element in each block to avoid the ambiguity
      // between front == tail meaning "empty" and "full".
      // So the effective number of slots that are guaranteed to be usable at any time is the block size - 1 times the
      // number of blocks - 1. Solving for maxSize and applying a ceiling to the division gives us (after simplifying):
      size_t initialBlockCount = (maxSize + MAX_BLOCK_SIZE * 2 - 3) / (MAX_BLOCK_SIZE - 1);
      largestBlockSize = MAX_BLOCK_SIZE;
      Block* lastBlock = nullptr;
      for (size_t i = 0; i != initialBlockCount; ++i) {
        Block* block = make_block(largestBlockSize);
        if (block == nullptr) {
          abort();
        }
        if (firstBlock == nullptr) {
          firstBlock = block;
        }
        else {
          lastBlock->next = block;
        }
        lastBlock = block;
        block->next = firstBlock;
      }
    }
    else {
      firstBlock = make_block(largestBlockSize);
      if (firstBlock == nullptr) {
        abort();
      }
      firstBlock->next = firstBlock;
    }
    frontBlock = firstBlock;
    tailBlock = firstBlock;
    
    // Make sure the reader/writer threads will have the initialized memory setup above:
    fence(memory_order_sync);
  }

References ceilToPow2(), fence(), frontBlock, largestBlockSize, make_block(), MAX_BLOCK_SIZE, memory_order_sync, ReaderWriterQueue::Block::next, and tailBlock.

Here is the call graph for this function:

~ReaderWriterQueue()

AE_NO_TSAN ReaderWriterQueue::~ReaderWriterQueue ( )

inline

Definition at line 132 of file readerwriterqueue.h.

  {
    // Make sure we get the latest version of all variables from other CPUs:
    fence(memory_order_sync);
 
    // Destroy any remaining objects in queue and free memory
    Block* frontBlock_ = frontBlock;
    Block* block = frontBlock_;
    do {
      Block* nextBlock = block->next;
      UINT8* rawBlock = block->rawThis;
      block->~Block();
      std::free(rawBlock);
      block = nextBlock;
    } while (block != frontBlock_);
  }

References fence(), frontBlock, memory_order_sync, ReaderWriterQueue::Block::next, and ReaderWriterQueue::Block::rawThis.

Here is the call graph for this function:

Member Function Documentation

align_for()

template<typename U >

static AE_FORCEINLINE UINT8* ReaderWriterQueue::align_for ( UINT8 *  ptr )

inlinestaticprivate

Definition at line 490 of file readerwriterqueue.h.

  {
    const std::size_t alignment = std::alignment_of<U>::value;
    return ptr + (alignment - (reinterpret_cast<std::uintptr_t>(ptr) % alignment)) % alignment;
  }

ceilToPow2()

static AE_FORCEINLINE size_t ReaderWriterQueue::ceilToPow2 ( size_t  x )

inlinestaticprivate

Definition at line 475 of file readerwriterqueue.h.

  {
    // From http://graphics.stanford.edu/~seander/bithacks.html#RoundUpPowerOf2
    --x;
    x |= x >> 1;
    x |= x >> 2;
    x |= x >> 4;
    for (size_t i = 1; i < sizeof(size_t); i <<= 1) {
      x |= x >> (i << 3);
    }
    ++x;
    return x;
  }

Referenced by ReaderWriterQueue().

Here is the caller graph for this function:

enqueue()

AE_FORCEINLINE bool ReaderWriterQueue::enqueue ( UINT8 *const &  element )

inline

Definition at line 156 of file readerwriterqueue.h.

  {
    return inner_enqueue(CanAlloc,element);
  }

References CanAlloc, and inner_enqueue().

Referenced by BlockingReaderWriterQueue::enqueue().

Here is the call graph for this function:

Here is the caller graph for this function:

inner_enqueue()

bool ReaderWriterQueue::inner_enqueue ( AllocationMode  canAlloc, UINT8 *const &  element  )

inlineprivate

Definition at line 381 of file readerwriterqueue.h.

  {
 
    // High-level pseudocode (assuming we're allowed to alloc a new block):
    // If room in tail block, add to tail
    // Else check next block
    //     If next block is not the head block, enqueue on next block
    //     Else create a new block and enqueue there
    //     Advance tail to the block we just enqueued to
 
    Block* tailBlock_ = tailBlock.load();
    size_t blockFront = tailBlock_->localFront;
    size_t blockTail = tailBlock_->tail.load();
 
    size_t nextBlockTail = (blockTail + 1) & tailBlock_->sizeMask;
    if (nextBlockTail != blockFront || nextBlockTail != (tailBlock_->localFront = tailBlock_->front.load())) {
      fence(memory_order_acquire);
      // This block has room for at least one more element
      tailBlock_->data[blockTail]= element;
 
 
      fence(memory_order_release);
      tailBlock_->tail = nextBlockTail;
    }
    else {
      fence(memory_order_acquire);
      if (tailBlock_->next.load() != frontBlock) {
        // Note that the reason we can't advance to the frontBlock and start adding new entries there
        // is because if we did, then dequeue would stay in that block, eventually reading the new values,
        // instead of advancing to the next full block (whose values were enqueued first and so should be
        // consumed first).
 
        fence(memory_order_acquire);    // Ensure we get latest writes if we got the latest frontBlock
 
        // tailBlock is full, but there's a free block ahead, use it
        Block* tailBlockNext = tailBlock_->next.load();
        size_t nextBlockFront = tailBlockNext->localFront = tailBlockNext->front.load();
        nextBlockTail = tailBlockNext->tail.load();
        fence(memory_order_acquire);
 
        // This block must be empty since it's not the head block and we
        // go through the blocks in a circle
        assert(nextBlockFront == nextBlockTail);
        tailBlockNext->localFront = nextBlockFront;
 
        tailBlockNext->data[nextBlockTail] = element;
 
        tailBlockNext->tail = (nextBlockTail + 1) & tailBlockNext->sizeMask;
 
        fence(memory_order_release);
        tailBlock = tailBlockNext;
      }
      else if (canAlloc == CanAlloc) {
        // tailBlock is full and there's no free block ahead; create a new block
        auto newBlockSize = largestBlockSize >= MAX_BLOCK_SIZE ? largestBlockSize : largestBlockSize * 2;
        auto newBlock = make_block(newBlockSize);
        if (newBlock == nullptr) {
          // Could not allocate a block!
          return false;
        }
        largestBlockSize = newBlockSize;
 
 
        newBlock->data[0] = element;
        assert(newBlock->front == 0);
        newBlock->tail = newBlock->localTail = 1;
 
        newBlock->next = tailBlock_->next.load();
        tailBlock_->next = newBlock;
 
        // Might be possible for the dequeue thread to see the new tailBlock->next
        // *without* seeing the new tailBlock value, but this is OK since it can't
        // advance to the next block until tailBlock is set anyway (because the only
        // case where it could try to read the next is if it's already at the tailBlock,
        // and it won't advance past tailBlock in any circumstance).
 
        fence(memory_order_release);
        tailBlock = newBlock;
      }
      else if (canAlloc == CannotAlloc) {
        // Would have had to allocate a new block to enqueue, but not allowed
        return false;
      }
      else {
        assert(false && "Should be unreachable code");
        return false;
      }
    }
 
    return true;
  }

References CanAlloc, CannotAlloc, ReaderWriterQueue::Block::data, fence(), ReaderWriterQueue::Block::front, frontBlock, largestBlockSize, weak_atomic< T >::load(), ReaderWriterQueue::Block::localFront, make_block(), MAX_BLOCK_SIZE, memory_order_acquire, memory_order_release, ReaderWriterQueue::Block::next, ReaderWriterQueue::Block::sizeMask, ReaderWriterQueue::Block::tail, and tailBlock.

Referenced by enqueue().

Here is the call graph for this function:

Here is the caller graph for this function:

make_block()

static Block* ReaderWriterQueue::make_block ( size_t  capacity )

inlinestaticprivate

Definition at line 532 of file readerwriterqueue.h.

  {
    // Allocate enough memory for the block itself, as well as all the elements it will contain
    UINT size = sizeof(Block) + std::alignment_of<Block>::value - 1;
    size += sizeof(UINT8*) * capacity + std::alignment_of<UINT8*>::value - 1;
    UINT8* newBlockRaw = static_cast<UINT8*>(std::malloc(size));
    if (newBlockRaw == nullptr) {
      return nullptr;
    }
    
    UINT8* newBlockAligned = align_for<Block>(newBlockRaw);
    UINT8* newBlockData = align_for<UINT8*>(newBlockAligned + sizeof(Block));
    return new (newBlockAligned) Block(capacity, newBlockRaw, newBlockData);
  }

Referenced by inner_enqueue(), and ReaderWriterQueue().

Here is the caller graph for this function:

peek()

UINT8* ReaderWriterQueue::peek ( )

inline

Definition at line 259 of file readerwriterqueue.h.

  {
    // See try_dequeue() for reasoning
 
    Block* frontBlock_ = frontBlock.load();
    size_t blockTail = frontBlock_->localTail;
    size_t blockFront = frontBlock_->front.load();
    
    if (blockFront != blockTail || blockFront != (frontBlock_->localTail = frontBlock_->tail.load())) {
      fence(memory_order_acquire);
    non_empty_front_block:
      return reinterpret_cast<UINT8*>(frontBlock_->data + blockFront * sizeof(UINT8*));
    }
    else if (frontBlock_ != tailBlock.load()) {
      fence(memory_order_acquire);
      frontBlock_ = frontBlock.load();
      blockTail = frontBlock_->localTail = frontBlock_->tail.load();
      blockFront = frontBlock_->front.load();
      fence(memory_order_acquire);
      
      if (blockFront != blockTail) {
        goto non_empty_front_block;
      }
      
      Block* nextBlock = frontBlock_->next;
      
      size_t nextBlockFront = nextBlock->front.load();
      fence(memory_order_acquire);
 
      assert(nextBlockFront != nextBlock->tail.load());
      return reinterpret_cast<UINT8*>(nextBlock->data + nextBlockFront * sizeof(UINT8*));
    }
    
    return nullptr;
  }

References ReaderWriterQueue::Block::data, fence(), ReaderWriterQueue::Block::front, frontBlock, weak_atomic< T >::load(), ReaderWriterQueue::Block::localTail, memory_order_acquire, ReaderWriterQueue::Block::next, ReaderWriterQueue::Block::tail, and tailBlock.

Referenced by BlockingReaderWriterQueue::peek().

Here is the call graph for this function:

Here is the caller graph for this function:

pop()

bool ReaderWriterQueue::pop ( )

inline

Definition at line 298 of file readerwriterqueue.h.

  {
    // See try_dequeue() for reasoning
    
    Block* frontBlock_ = frontBlock.load();
    size_t blockTail = frontBlock_->localTail;
    size_t blockFront = frontBlock_->front.load();
    
    if (blockFront != blockTail || blockFront != (frontBlock_->localTail = frontBlock_->tail.load())) {
      fence(memory_order_acquire);
      
    non_empty_front_block:
      auto element = reinterpret_cast<UINT8*>(frontBlock_->data + blockFront * sizeof(UINT8));
      //element->~T();
 
      blockFront = (blockFront + 1) & frontBlock_->sizeMask;
 
      fence(memory_order_release);
      frontBlock_->front = blockFront;
    }
    else if (frontBlock_ != tailBlock.load()) {
      fence(memory_order_acquire);
      frontBlock_ = frontBlock.load();
      blockTail = frontBlock_->localTail = frontBlock_->tail.load();
      blockFront = frontBlock_->front.load();
      fence(memory_order_acquire);
      
      if (blockFront != blockTail) {
        goto non_empty_front_block;
      }
      
      // Front block is empty but there's another block ahead, advance to it
      Block* nextBlock = frontBlock_->next;
      
      size_t nextBlockFront = nextBlock->front.load();
      size_t nextBlockTail = nextBlock->localTail = nextBlock->tail.load();
      fence(memory_order_acquire);
 
      assert(nextBlockFront != nextBlockTail);
      AE_UNUSED(nextBlockTail);
 
      fence(memory_order_release);
      frontBlock = frontBlock_ = nextBlock;
 
      compiler_fence(memory_order_release);
 
      auto element = reinterpret_cast<UINT8*>(frontBlock_->data + nextBlockFront * sizeof(UINT8*));
//      element->~T();
 
      nextBlockFront = (nextBlockFront + 1) & frontBlock_->sizeMask;
      
      fence(memory_order_release);
      frontBlock_->front = nextBlockFront;
    }
    else {
      // No elements in current block and no other block to advance to
      return false;
    }
 
    return true;
  }

References AE_UNUSED, compiler_fence(), ReaderWriterQueue::Block::data, fence(), ReaderWriterQueue::Block::front, frontBlock, weak_atomic< T >::load(), ReaderWriterQueue::Block::localTail, memory_order_acquire, memory_order_release, ReaderWriterQueue::Block::next, ReaderWriterQueue::Block::sizeMask, ReaderWriterQueue::Block::tail, and tailBlock.

Referenced by BlockingReaderWriterQueue::pop().

Here is the call graph for this function:

Here is the caller graph for this function:

size_approx()

size_t ReaderWriterQueue::size_approx ( ) const

inline

Definition at line 362 of file readerwriterqueue.h.

  {
    size_t result = 0;
    Block* frontBlock_ = frontBlock.load();
    Block* block = frontBlock_;
    do {
      fence(memory_order_acquire);
      size_t blockFront = block->front.load();
      size_t blockTail = block->tail.load();
      result += (blockTail - blockFront) & block->sizeMask;
      block = block->next.load();
    } while (block != frontBlock_);
    return result;
  }

References fence(), ReaderWriterQueue::Block::front, frontBlock, weak_atomic< T >::load(), memory_order_acquire, ReaderWriterQueue::Block::next, ReaderWriterQueue::Block::sizeMask, and ReaderWriterQueue::Block::tail.

Here is the call graph for this function:

try_dequeue()

bool ReaderWriterQueue::try_dequeue ( UINT8 *&  result )

inline

Definition at line 165 of file readerwriterqueue.h.

  {
 
    // High-level pseudocode:
    // Remember where the tail block is
    // If the front block has an element in it, dequeue it
    // Else
    //     If front block was the tail block when we entered the function, return false
    //     Else advance to next block and dequeue the item there
 
    // Note that we have to use the value of the tail block from before we check if the front
    // block is full or not, in case the front block is empty and then, before we check if the
    // tail block is at the front block or not, the producer fills up the front block *and
    // moves on*, which would make us skip a filled block. Seems unlikely, but was consistently
    // reproducible in practice.
    // In order to avoid overhead in the common case, though, we do a double-checked pattern
    // where we have the fast path if the front block is not empty, then read the tail block,
    // then re-read the front block and check if it's not empty again, then check if the tail
    // block has advanced.
    
    Block* frontBlock_ = frontBlock.load();
    size_t blockTail = frontBlock_->localTail;
    size_t blockFront = frontBlock_->front.load();
    
    if (blockFront != blockTail || blockFront != (frontBlock_->localTail = frontBlock_->tail.load())) {
      fence(memory_order_acquire);
      
    non_empty_front_block:
      // Front block not empty, dequeue from here
      result = frontBlock_->data[blockFront];
      //element->~T();
 
      blockFront = (blockFront + 1) & frontBlock_->sizeMask;
 
      fence(memory_order_release);
      frontBlock_->front = blockFront;
    }
    else if (frontBlock_ != tailBlock.load()) {
      fence(memory_order_acquire);
 
      frontBlock_ = frontBlock.load();
      blockTail = frontBlock_->localTail = frontBlock_->tail.load();
      blockFront = frontBlock_->front.load();
      fence(memory_order_acquire);
      
      if (blockFront != blockTail) {
        // Oh look, the front block isn't empty after all
        goto non_empty_front_block;
      }
      
      // Front block is empty but there's another block ahead, advance to it
      Block* nextBlock = frontBlock_->next;
      // Don't need an acquire fence here since next can only ever be set on the tailBlock,
      // and we're not the tailBlock, and we did an acquire earlier after reading tailBlock which
      // ensures next is up-to-date on this CPU in case we recently were at tailBlock.
 
      size_t nextBlockFront = nextBlock->front.load();
      size_t nextBlockTail = nextBlock->localTail = nextBlock->tail.load();
      fence(memory_order_acquire);
 
      // Since the tailBlock is only ever advanced after being written to,
      // we know there's for sure an element to dequeue on it
      assert(nextBlockFront != nextBlockTail);
      AE_UNUSED(nextBlockTail);
 
      // We're done with this block, let the producer use it if it needs
      fence(memory_order_release);    // Expose possibly pending changes to frontBlock->front from last dequeue
      frontBlock = frontBlock_ = nextBlock;
 
      compiler_fence(memory_order_release); // Not strictly needed
 
      result = frontBlock_->data [nextBlockFront];
      
      //element->~T();
 
      nextBlockFront = (nextBlockFront + 1) & frontBlock_->sizeMask;
      
      fence(memory_order_release);
      frontBlock_->front = nextBlockFront;
    }
    else {
      // No elements in current block and no other block to advance to
      return false;
    }
 
    return true;
  }

References AE_UNUSED, compiler_fence(), ReaderWriterQueue::Block::data, fence(), ReaderWriterQueue::Block::front, frontBlock, weak_atomic< T >::load(), ReaderWriterQueue::Block::localTail, memory_order_acquire, memory_order_release, ReaderWriterQueue::Block::next, ReaderWriterQueue::Block::sizeMask, ReaderWriterQueue::Block::tail, and tailBlock.

Referenced by BlockingReaderWriterQueue::try_dequeue(), BlockingReaderWriterQueue::wait_dequeue(), and BlockingReaderWriterQueue::wait_dequeue_timed().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

cachelineFiller

char ReaderWriterQueue::cachelineFiller[MOODYCAMEL_CACHE_LINE_SIZE - sizeof(weak_atomic< Block * >)]

private

Definition at line 550 of file readerwriterqueue.h.

frontBlock

weak_atomic<Block*> ReaderWriterQueue::frontBlock

private

Definition at line 548 of file readerwriterqueue.h.

Referenced by inner_enqueue(), peek(), pop(), ReaderWriterQueue(), size_approx(), try_dequeue(), and ~ReaderWriterQueue().

largestBlockSize

size_t ReaderWriterQueue::largestBlockSize

private

Definition at line 553 of file readerwriterqueue.h.

Referenced by inner_enqueue(), and ReaderWriterQueue().

tailBlock

weak_atomic<Block*> ReaderWriterQueue::tailBlock

private

Definition at line 551 of file readerwriterqueue.h.

Referenced by inner_enqueue(), peek(), pop(), ReaderWriterQueue(), and try_dequeue().

value_type

UINT8* ReaderWriterQueue::value_type

Definition at line 75 of file readerwriterqueue.h.

---

The documentation for this class was generated from the following file:

• readerwriterqueue.h