Add parseAPI/LockFreeQueue.h

docs/parseAPI/developer/API.rst

@@ -27,6 +27,7 @@ ParseAPI
   InstructionAdapter.h
   JumpTableFormatPred.h
   JumpTableIndexPred.h
+  LockFreeQueue.h
   LoopAnalyzer.h
   ParseData.h
   ParserDetails.h
@@ -35,4 +36,4 @@ ParseAPI
   StackTamperVisitor.h
   SymbolicExpression.h
   ThunkData.h
-  util.h
+  util.h

docs/parseAPI/developer/LockFreeQueue.h.rst

@@ -0,0 +1,75 @@
+.. _`sec-dev:LockFreeQueue.h`:
+
+LockFreeQueue.h
+###############
+
+.. cpp:class:: template<typename T> LockFreeQueueItem
+
+  .. cpp:function:: LockFreeQueueItem(T __value)
+  .. cpp:function:: void setNext(item_type *__next)
+  .. cpp:function:: void setNextPending()
+  .. cpp:function:: item_type *next()
+  .. cpp:function:: T value()
+
+.. cpp:class:: template<typename T> LockFreeQueueIterator
+
+  Designed for use in a context where where only insert_chain operations
+  that have completed their exchange may be concurrent with iteration on
+  the queue.
+
+  .. note:: This class models the C++ `LegacyForwardIterator <https://en.cppreference.com/w/cpp/named_req/ForwardIterator>`_ concept.
+
+  .. cpp:type:: T value_type
+  .. cpp:type:: T* pointer
+  .. cpp:type:: T& reference
+  .. cpp:type:: std::ptrdiff_t difference_type
+  .. cpp:type:: std::forward_iterator_tag iterator_category
+
+.. cpp:class:: template<typename T> LockFreeQueue
+
+  .. cpp:type:: LockFreeQueueIterator<T> iterator
+  .. cpp:type:: LockFreeQueueItem<T> item_type
+
+  .. cpp:function:: LockFreeQueue(item_type *_head = 0)
+
+  .. cpp:function:: void insert(T value)
+
+      Inserts a singleton at the head of the queue.
+
+      .. note:: This operation is wait-free unless the allocator blocks
+
+  .. cpp:function:: void splice(LockFreeQueue<T> &q)
+
+    Steal the linked list from q and insert it at the front of this queue.
+
+    Wait-free for concurrent use.
+
+  .. cpp:function:: item_type *peek()
+
+    Inspects the head of the queue.
+
+    Wait-free for concurrent use.
+
+  .. cpp:function:: item_type *steal()
+
+      Grabs the contents of the queue for your own private use.
+
+  .. cpp:function:: item_type *pop()
+
+      Designed for use in a context where where only insert_chain
+      operations that have completed their exchange may be concurrent.
+
+  .. cpp:function:: iterator begin()
+
+      Designed for use in a context where where only insert_chain
+      operations that have completed their exchange may be concurrent.
+
+  .. cpp:function:: iterator end()
+
+      Designed for use in a context where where only insert_chain
+      operations that have completed their exchange may be concurrent.
+
+  .. cpp:function:: void clear()
+
+      Designed for use in a context where where only insert_chain
+      operations that have completed their exchange may be concurrent.

docs/parseAPI/public/API.rst

@@ -15,7 +15,6 @@ ParseAPI
   InstructionAdapter.h
   InstructionSource.h
   Location.h
-  LockFreeQueue.h
   ParseCallback.h
   ParseContainers.h
   SymLiteCodeSource.h

parseAPI/h/LockFreeQueue.h

@@ -93,9 +93,6 @@ class LockFreeQueueItem {
 };
 
 
-// designed for use in a context where where only insert_chain operations
-// that have completed their exchange may be concurrent with iteration on
-// the queue
 template<typename T>
 class LockFreeQueueIterator {
 private:
@@ -142,16 +139,11 @@ class LockFreeQueue {
   LockFreeQueue(item_type *_head = 0) : head(_head) {}
 
 public: 
-  // wait-free member functions designed for concurrent use
-
-  // insert a singleton at the head of the queue
-  // note: this operation is wait-free unless the allocator blocks 
   void insert(T value) {
     item_type *entry = new item_type(value);
     insert_chain(entry, entry);
   }
 
-  // steal the linked list from q and insert it at the front of this queue
   void splice(LockFreeQueue<T> &q) {
     if (q.peek()) { // only empty q if it is non-empty 
       item_type *first = q.steal();
@@ -165,22 +157,17 @@ class LockFreeQueue {
     }
   }
 
-  // inspect the head of the queue
   item_type *peek() { 
       item_type* ret = head.load();
       return ret; 
   }
 
-  // grab the contents of the queue for your own private use
   item_type *steal() { 
       item_type* ret = head.exchange(0);
       return ret; 
   }
 
 public:
-  // designed for use in a context where where only insert_chain 
-  // operations that have completed their exchange may be concurrent
-
   item_type *pop() { 
     item_type *first = head.load();
     if (first) {