Added some documentation.

Author: dustinhiatt-wf

README.md

@@ -20,6 +20,8 @@ Still pretty specific to gotable, but contains logic required to maintain graph
 #### Queue: 
 Package contains both a normal and priority queue.  Both implementations never block on send and grow as much as necessary.  Both also only return errors if you attempt to push to a disposed queue and will not panic like sending a message on a closed channel.  The priority queue also allows you to place items in priority order inside the queue.  If you give a useful hint to the regular queue, it is actually faster than a channel.  The priority queue is somewhat slow currently and targeted for an update to a Fibonacci heap.
 
+Also included in the queue package is a MPMC threadsafe ring buffer. This is a block full/empty queue, but will return a blocked thread if the queue is disposed while a thread is blocked.  This can be used to synchronize goroutines and ensure goroutines quit so objects can be GC'd.  Threadsafety is acheived using only CAS operations making this queue quite fast.  Benchmarks can be found in that package.
+
 #### Range Tree: 
 Useful to determine if n-dimensional points fall within an n-dimensional range.  Not a typical range tree however, as we are actually using an n-dimensional sorted list of points as this proved to be simpler and faster than attempting a traditional range tree while saving space on any dimension greater than one.  Inserts are typical BBST times at O(log n^d) where d is the number of dimensions.
 

queue/queue.go

@@ -24,10 +24,31 @@ as opposed to panicking as with channels.  Queues will grow with unbounded
 behavior as opposed to channels which can be buffered but will pause
 while a thread attempts to put to a full channel.
 
-TODO: Unify the two types of queue to the same interface.
-TODO: Implement an even faster lockless circular buffer.
+Recently added is a lockless ring buffer using the same basic C design as
+found here:
+
+http://www.1024cores.net/home/lock-free-algorithms/queues/bounded-mpmc-queue
+
+Modified for use with Go with the addition of some dispose semantics providing
+the capability to release blocked threads.  This works for both puts
+and gets, either will return an error if they are blocked and the buffer
+is disposed.  This could serve as a signal to kill a goroutine.  All threadsafety
+is acheived using CAS operations, making this buffer pretty quick.
+
+Benchmarks:
+BenchmarkPriorityQueue-8	 		2000000	       782 ns/op
+BenchmarkQueue-8	 		 		2000000	       671 ns/op
+BenchmarkChannel-8	 		 		1000000	      2083 ns/op
+BenchmarkQueuePut-8	   		   		20000	     84299 ns/op
+BenchmarkQueueGet-8	   		   		20000	     80753 ns/op
+BenchmarkExecuteInParallel-8	    20000	     68891 ns/op
+BenchmarkRBLifeCycle-8				10000000	       177 ns/op
+BenchmarkRBPut-8					30000000	        58.1 ns/op
+BenchmarkRBGet-8					50000000	        26.8 ns/op
+
+TODO: We really need a Fibonacci heap for the priority queue.
+TODO: Unify the types of queue to the same interface.
 */
-
 package queue
 
 import (

queue/ring.go

@@ -16,16 +16,10 @@ limitations under the License.
 package queue
 
 import (
-	"errors"
-	"log"
 	"runtime"
 	"sync/atomic"
 )
 
-func init() {
-	log.Printf(`I HATE THIS.`)
-}
-
 // roundUp takes a uint64 greater than 0 and rounds it up to the next
 // power of 2.
 func roundUp(v uint64) uint64 {
@@ -47,6 +41,12 @@ type node struct {
 
 type nodes []*node
 
+// RingBuffer is a MPMC buffer that achieves threadsafety with CAS operations
+// only.  A put on full or get on empty call will block until an item
+// is put or retrieved.  Calling Dispose on the RingBuffer will unblock
+// any blocked threads with an error.  This buffer is similar to the buffer
+// described here: http://www.1024cores.net/home/lock-free-algorithms/queues/bounded-mpmc-queue
+// with some minor additions.
 type RingBuffer struct {
 	nodes                          nodes
 	queue, dequeue, mask, disposed uint64
@@ -61,6 +61,9 @@ func (rb *RingBuffer) init(size uint64) {
 	rb.mask = size - 1 // so we don't have to do this with every put/get operation
 }
 
+// Put adds the provided item to the queue.  If the queue is full, this
+// call will block until an item is added to the queue or Dispose is called
+// on the queue.  An error will be returned if the queue is disposed.
 func (rb *RingBuffer) Put(item interface{}) error {
 	var n *node
 	pos := atomic.LoadUint64(&rb.queue)
@@ -78,7 +81,7 @@ L:
 				break L
 			}
 		case dif < 0:
-			return errors.New(`Full.`)
+			panic(`Ring buffer in a compromised state during a put operation.`)
 		default:
 			pos = atomic.LoadUint64(&rb.queue)
 		}
@@ -90,6 +93,10 @@ L:
 	return nil
 }
 
+// Get will return the next item in the queue.  This call will block
+// if the queue is empty.  This call will unblock when an item is added
+// to the queue or Dispose is called on the queue.  An error will be returned
+// if the queue is disposed.
 func (rb *RingBuffer) Get() (interface{}, error) {
 	var n *node
 	pos := atomic.LoadUint64(&rb.dequeue)
@@ -107,7 +114,7 @@ L:
 				break L
 			}
 		case dif < 0:
-			return nil, errors.New(`Queue empty.`)
+			panic(`Ring buffer in compromised state during a get operation.`)
 		default:
 			pos = atomic.LoadUint64(&rb.dequeue)
 		}
@@ -119,22 +126,31 @@ L:
 	return data, nil
 }
 
+// Len returns the number of items in the queue.
 func (rb *RingBuffer) Len() uint64 {
 	return atomic.LoadUint64(&rb.queue) - atomic.LoadUint64(&rb.dequeue)
 }
 
+// Cap returns the capacity of this ring buffer.
 func (rb *RingBuffer) Cap() uint64 {
 	return uint64(len(rb.nodes))
 }
 
+// Dispose will dispose of this queue and free any blocked threads
+// in the Put and/or Get methods.  Calling those methods on a disposed
+// queue will return an error.
 func (rb *RingBuffer) Dispose() {
 	atomic.CompareAndSwapUint64(&rb.disposed, 0, 1)
 }
 
+// IsDisposed will return a bool indicating if this queue has been
+// disposed.
 func (rb *RingBuffer) IsDisposed() bool {
 	return atomic.LoadUint64(&rb.disposed) == 1
 }
 
+// NewRingBuffer will allocate, initialize, and return a ring buffer
+// with the specified size.
 func NewRingBuffer(size uint64) *RingBuffer {
 	rb := &RingBuffer{}
 	rb.init(size)