add queue.Peek() functionality

Author: Mike Atlas

queue/error.go

@@ -25,4 +25,7 @@ var (
 
 	// ErrTimeout is returned when an applicable queue operation times out.
 	ErrTimeout = errors.New(`queue: poll timed out`)
+
+	// ErrUnknown is returned if the error state was unusual and unexpected.
+	ErrUnknown = errors.New(`queue: unknown error`)
 )

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)[length-1], 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 peekItem, nil
+	}
+
+	return nil, ErrUnknown
+}
+
 // 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,28 @@ func BenchmarkChannel(b *testing.B) {
 	wg.Wait()
 }
 
+func TestPeek(t *testing.T) {
+	q := New(10)
+	q.Put(`a`)
+	q.Put(`b`)
+	q.Put(`c`)
+	result, err := q.Peek()
+	expected := `c`
+
+	assert.Nil(t, err)
+	assert.Equal(t, expected, result)
+	assert.Equal(t, q.Len(), int64(3))
+}
+
+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`)