This package (repo) provides an implementation of a thread-safe, blocking, generic dequeue that can be used as FIFO or LIFO or a hybrid between the 2.
To install this package, you will need to setup your go workspace first. Also this package requires go v1.18 or later.
-
To install the package run the following command:
go get github.com/AmrSaber/go-blocking-dequeue
-
To import the package:
import "github.com/AmrSaber/go-blocking-dequeue"
-
Use the package in code using
blocking_dequeue
module (see usage below).
To create a new dequeue use blocking_dequeue.NewBlockingDequeue
function as follows:
// Integers dequeue
buffer := make([]int, 10)
integersDequeue := blocking_dequeue.NewBlockingDequeue(buffer)
integersDequeue.PushBack(10)
// Strings dequeue
buffer := make([]string, 10)
stringsDequeue := blocking_dequeue.NewBlockingDequeue(buffer)
stringsDequeue.PushBack("hello")
type User struct {
Username string
Age int
}
// Dequeue of custom type
buffer := make([]User, 10)
usersDequeue := blocking_dequeue.NewBlockingDequeue(buffer)
usersDequeue.PushBack(User{ "Amr", 25 })
// Pointer dequeue
buffer := make([]*User, 10)
usersPtrDequeue := blocking_dequeue.NewBlockingDequeue(buffer)
usersPtrDequeue.PushBack(&User{ "Amr", 25 })
The dequeue is implemented using generics, so it can hold any datatype, just create a buffer with the desired datatype and pass it to the creation function.
The capacity of the dequeue is the length of the provided buffer.
buffer := make([]int, 10)
dq := blocking_dequeue.NewBlockingDequeue(buffer)
dq.PushBack(1) // Pushed to the end of the dequeue
dq.PushBack(2) // Pushed to the end of the dequeue
dq.PushBack(3) // Pushed to the end of the dequeue
dq.PopFront() // Pops from the top, returns 1
dq.PopFront() // Pops from the top, returns 2
dq.PopFront() // Pops from the top, returns 3
buffer := make([]int, 10)
dq := blocking_dequeue.NewBlockingDequeue(buffer)
dq.PushFront(1) // Pushed to the start of the dequeue
dq.PushFront(2) // Pushed to the start of the dequeue
dq.PushFront(3) // Pushed to the start of the dequeue
dq.PopFront() // Pops from the top, returns 3
dq.PopFront() // Pops from the top, returns 2
dq.PopFront() // Pops from the top, returns 1
The package itself exposes 1 function NewBlockingQueue
that is used to create a new dequeue and return a pointer to it.
The dequeue itself exposes the following methods:
PushFront
,PushBack
PopFront
,PopBack
PeekFront
,PeekBack
Size
,IsEmpty
,IsFull
The detailed documentation can be found at the related go packages page.
This dequeue is implemented using ring (or circular) buffer so all of the operations are done in O(1) time complexity.
However, due to the thread-safe nature, and all the lock/unlock/wait/signal logic, it's expected to be a bit slower than plain ring buffer. If you intend to use this dequeue in a single threaded context (where only a single goroutine will have access to it) it's advised to use plain circular buffer or the built-in container/list
instead.
If you intend to use it as a limited capacity queue to communicate between goroutines, it would be better to use built-in channels with buffer, so instead of
buffer := make([]int, 10)
dq := blocking_dequeue.NewBlockingDequeue(buffer)
// Push to queue
dq.PushBack(1)
// Pop from queue
dq.PopFront()
You better use
ch := make(chan int, 10)
// Push to queue
ch <- 1
// Pop from queue
<- ch
That is unless you need access the other provided methods, such as Peek
variations, Size
, IsFull
, and so on...
No benchmarking against plain ring buffer or the built-in container/list
nor channels yet. But it's in the plan.
If you find a bug, you are welcome to create a ticket on github or create a PR with the fix directly mentioning in the description of the PR what is the problem and how your PR fixes it.
If you want to suggest a feature (even if you have no idea how it will be implemented) feel free to open a ticket with it.