Merge pull request #139 from mikeatlas/queue-peek

added queue.Peek() functionality

Author: dustinhiatt-wf

queue/error.go

@@ -25,4 +25,8 @@ var (
 
 	// ErrTimeout is returned when an applicable queue operation times out.
 	ErrTimeout = errors.New(`queue: poll timed out`)
+
+	// ErrEmptyQueue is returned when an non-applicable queue operation was called
+	// due to the queue's empty item state
+	ErrEmptyQueue = errors.New(`queue: empty queue`)
 )

queue/queue.go

@@ -95,6 +95,16 @@ func (items *items) get(number int64) []interface{} {
 	return returnItems
 }
 
+func (items *items) peek() (interface{}, bool) {
+	length := len(*items)
+
+	if length == 0 {
+		return nil, false
+	}
+
+	return (*items)[0], true
+}
+
 func (items *items) getUntil(checker func(item interface{}) bool) []interface{} {
 	length := len(*items)
 
@@ -239,6 +249,24 @@ func (q *Queue) Poll(number int64, timeout time.Duration) ([]interface{}, error)
 	return items, nil
 }
 
+// Peek returns a the first item in the queue by value
+// without modifying the queue.
+func (q *Queue) Peek() (interface{}, error) {
+	q.lock.Lock()
+	defer q.lock.Unlock()
+
+	if q.disposed {
+		return nil, ErrDisposed
+	}
+
+	peekItem, ok := q.items.peek()
+	if !ok {
+		return nil, ErrEmptyQueue
+	}
+
+	return peekItem, nil
+}
+
 // TakeUntil takes a function and returns a list of items that
 // match the checker until the checker returns false.  This does not
 // wait if there are no items in the queue.

queue/queue_test.go

@@ -329,6 +329,32 @@ func BenchmarkChannel(b *testing.B) {
 	wg.Wait()
 }
 
+func TestPeek(t *testing.T) {
+	q := New(10)
+	q.Put(`a`)
+	q.Put(`b`)
+	q.Put(`c`)
+	peekResult, err := q.Peek()
+	peekExpected := `a`
+	assert.Nil(t, err)
+	assert.Equal(t, q.Len(), int64(3))
+	assert.Equal(t, peekExpected, peekResult)
+
+	popResult, err := q.Get(1)
+	assert.Nil(t, err)
+	assert.Equal(t, peekResult, popResult[0])
+	assert.Equal(t, q.Len(), int64(2))
+}
+
+func TestPeekOnDisposedQueue(t *testing.T) {
+	q := New(10)
+	q.Dispose()
+	result, err := q.Peek()
+
+	assert.Nil(t, result)
+	assert.IsType(t, ErrDisposed, err)
+}
+
 func TestTakeUntil(t *testing.T) {
 	q := New(10)
 	q.Put(`a`, `b`, `c`)