gammazero / deque

Fast ring-buffer deque (double-ended queue)

deque

Fast ring-buffer deque (double-ended queue) implementation.

For a pictorial description, see the Deque diagram

Installation

$ go get github.com/gammazero/deque

Deque data structure

Deque generalizes a queue and a stack, to efficiently add and remove items at either end with O(1) performance. Queue (FIFO) operations are supported using PushBack and PopFront. Stack (LIFO) operations are supported using PushBack and PopBack.

Ring-buffer Performance

This deque implementation is optimized for CPU and GC performance. The circular buffer automatically re-sizes by powers of two, growing when additional capacity is needed and shrinking when only a quarter of the capacity is used, and uses bitwise arithmetic for all calculations. Since growth is by powers of two, adding elements will only cause O(log n) allocations. A minimum capacity can be set so that there is no resizing at or below that specified amount.

The ring-buffer implementation improves memory and time performance with fewer GC pauses, compared to implementations based on slices and linked lists. By wrapping around the buffer, previously used space is reused, making allocation unnecessary until all buffer capacity is used. If the deque is only filled and then completely emptied before being filled again, then the ring structure offers little benefit for memory reuse over a slice.

For maximum speed, this deque implementation leaves concurrency safety up to the application to provide, however the application chooses, if needed at all.

Reading Empty Deque

Since it is OK for the deque to contain a nil value, it is necessary to either panic or return a second boolean value to indicate the deque is empty, when reading or removing an element. This deque panics when reading from an empty deque. This is a run-time check to help catch programming errors, which may be missed if a second return value is ignored. Simply check Deque.Len() before reading from the deque.

Generics

Deque uses generics to create a Deque that contains items of the type specified. To create a Deque that holds a specific type, provide a type argument to New or with the variable declaration. For example:

    stringDeque := deque.New[string]()
    var intDeque deque.Deque[int]

Example

package main

import (
    "fmt"
    "github.com/gammazero/deque"
)

func main() {
    var q deque.Deque[string]
    q.PushBack("foo")
    q.PushBack("bar")
    q.PushBack("baz")

    fmt.Println(q.Len())   // Prints: 3
    fmt.Println(q.Front()) // Prints: foo
    fmt.Println(q.Back())  // Prints: baz

    q.PopFront() // remove "foo"
    q.PopBack()  // remove "baz"

    q.PushFront("hello")
    q.PushBack("world")

    // Consume deque and print elements.
    for q.Len() != 0 {
        fmt.Println(q.PopFront())
    }
}

Uses

Deque can be used as both a:

• Queue using PushBack and PopFront
• Stack using PushBack and PopBack

deque's Issues

Benefits of this library?

What's the advantage, if any, of using this in place of standard slice?

Taken from Marwan Burelle's example on SO:

queue := make([]int, 0)
// Push to the queue
queue = append(queue, 1)
// Top (just get next element, don't remove it)
x = queue[0]
// Discard top element
queue = queue[1:]
// Is empty ?
if len(queue) == 0 {
    fmt.Println("Queue is empty !")
}

Does deque offer any benchmarks comparing it to standard slice implementations?

Feature request: Add search, delete, "insert after" functionality

In my use case I PushBack 99% of the time, but sometimes I wish to insert an element after a specific other one. O(n) performance would be fine. Search for and deleting an element would also be a fine addition. May I ask for these functions, pretty please? :)

replace `(q.head + n) & modBits` with next() in Rotate

q.head = (q.head - 1) & modBits
=>
q.head = q.prev(q.head)

q.head = (q.head + n) & modBits
=>
q.head = q.next(q.head + n - 1)

Returns zero and loses messages

Hey Andrew,

Can you tell me what I'm doing wrong?
From time to time the PopFront method returns nil, and some messages get lost?

Thank you!

package somepackage

import (
	"sync"
	"testing"
	"time"

	"github.com/gammazero/deque"
	"github.com/google/uuid"
	"github.com/jpillora/backoff"
)

func Test(t *testing.T) {
	dq := deque.New[*string]()

	count := 15000

	m := make([]*string, 0, count)

	wg := sync.WaitGroup{}
	wg.Add(2)

	go func() {
		for i := 0; i < count; i++ {
			if i%3000 == 0 {
				b := &backoff.Backoff{
					Factor: 2,
					Min:    time.Second * 2,
					Max:    time.Second * 10,
				}

				time.Sleep(b.Duration())
			}

			s := uuid.New().String()
			dq.PushBack(&s)
		}

		wg.Done()
	}()

	go func() {
		for {
			if len(m) == count {
				break
			}

			if dq.Len() == 0 {
				continue
			}

			s := dq.PopFront()
			if s == nil {
			} // sometime it's true

			m = append(m, s)
		}
		wg.Done()
	}()

	wg.Wait()
}

Ready for release?

Deque is a good utility, clear and simple to use, and fast.

Is it ready for a release version? It's overdue for one, IMO :-)

Meanwhile, here are some ideas for methods that you could add:

• push and insert slices - i.e. internalise the loop needed and reduce loop overhead
• add adaptors for the PopBack, PopFront and At methods to provide iterators (Go 1.23)
• add Full() bool method - a shortcut for q.Len() == q.Cap() which would be useful for anyone wanting to impose a maximum size or avoid resizing

codecov in .travis.yml - security issue

Good day,
https://codecov.io/bash recently outputted a security issue. Details can be found at https://about.codecov.io/security-update/

The following file and code are impacted. Please follow the recommended actions in the link above to secure your env and code integrity.
file: .travis.yml
Code:
after_success:

bash <(curl -s https://codecov.io/bash)

Add a method to Test whether container is empty

Feature Request

This function returns whether the deque container is empty (i.e. whether its size is 0) or not.

This function does not modify the container in any way.

• Parameters
  none

• Return Value
  true if the container size is 0, false otherwise.

Ref

https://www.cplusplus.com/reference/deque/deque/empty/

Function for rounding up to the nearest Power of 2.

I see that you're trying to round values using a for loop, but what you could do instead is this:

// Round up to the nearest power of 2
// It's way more faster than doing it in a loop. 
func ceilPow2(x uint32) uint32 {
	x = x - 1

	x = x | (x >> 1)
	x = x | (x >> 2)
	x = x | (x >> 4)
	x = x | (x >> 8)
	x = x | (x >> 16)

	return x + 1
}

// Any size values supplied here are rounded up to the nearest power of 2.
func New[T any](size ...int) *Deque[T] {
	var capacity, minimum int
	if len(size) >= 1 {
		capacity = size[0]
		if len(size) >= 2 {
			minimum = size[1]
		}
	}

	minCap := minCapacity
	if minCap < minimum {
		// Its safe to cast back to int since the initial value was of that type
		// and could never exceed 2147483647.
		minCap = int(ceilPow2(uint32(minimum)))
	}

	var buf []T
	if capacity != 0 {
		bufSize := minCap
		if bufSize < capacity {
			bufSize = int(ceilPow2(uint32(capacity)))
		}
		buf = make([]T, bufSize)
	}

	return &Deque[T]{
		buf:    buf,
		minCap: minCap,
	}
}

Let me know what your thought are.