Skip to content

Commit 9a2f3a1

Browse files
committed
update readme
1 parent 99cb61d commit 9a2f3a1

File tree

1 file changed

+21
-28
lines changed

1 file changed

+21
-28
lines changed

README.md

Lines changed: 21 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/AmrSaber/go-blocking-dequeue?color=blue&display_name=tag&sort=semver)
55
![GitHub license](https://img.shields.io/github/license/AmrSaber/go-blocking-dequeue)
66

7-
This package (repo) provides an implementation of a thread-safe, blocking, generic, infinite dequeue that can be used as FIFO or LIFO or a hybrid between the 2.
7+
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.
88

99
## Installation
1010

@@ -32,11 +32,13 @@ To create a new dequeue use `blocking_dequeue.NewBlockingDequeue` function as fo
3232

3333
```go
3434
// Integers dequeue
35-
integersDequeue := blocking_dequeue.NewBlockingDequeue[int]()
35+
buffer := make([]int, 10)
36+
integersDequeue := blocking_dequeue.NewBlockingDequeue(buffer)
3637
integersDequeue.PushBack(10)
3738

3839
// Strings dequeue
39-
stringsDequeue := blocking_dequeue.NewBlockingDequeue[string]()
40+
buffer := make([]string, 10)
41+
stringsDequeue := blocking_dequeue.NewBlockingDequeue(buffer)
4042
stringsDequeue.PushBack("hello")
4143

4244
type User struct {
@@ -45,36 +47,27 @@ type User struct {
4547
}
4648

4749
// Dequeue of custom type
48-
usersDequeue := blocking_dequeue.NewBlockingDequeue[User]()
50+
buffer := make([]User, 10)
51+
usersDequeue := blocking_dequeue.NewBlockingDequeue(buffer)
4952
usersDequeue.PushBack(User{ "Amr", 25 })
5053

5154
// Pointer dequeue
52-
usersPtrDequeue := blocking_dequeue.NewBlockingDequeue[*User]()
55+
buffer := make([]*User, 10)
56+
usersPtrDequeue := blocking_dequeue.NewBlockingDequeue(buffer)
5357
usersPtrDequeue.PushBack(&User{ "Amr", 25 })
5458
```
5559

56-
The dequeue is implemented using generics, so it can hold any datatype, just pass the data type you want between the square brackets `[ ]`.
60+
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.
5761

5862
### Capacity
5963

60-
You can set a capacity if you want (the default is unlimited capacity)
61-
62-
```go
63-
dequeue.SetCapacity(100) // Limit the dequeue to only carry 100 elements
64-
dequeue.SetCapacity(0) // Infinite capacity (the default)
65-
```
66-
67-
Some notes about setting the capacity:
68-
69-
- Pushing to the dequeue will block if it has full capacity, the goroutine will be blocked until some values are popped from the dequeue.
70-
- As in the above example, setting the capacity to 0 means having infinite capacity.
71-
- If you attempt the set the capacity to be lower than the current size of the dequeue, the method `SetCapacity` will return an error, and the capacity won't be updated. The same thing will also happen if you try to set the capacity with a negative number.
72-
- You can always set the capacity to 0 regardless of the current size.
64+
The capacity of the dequeue is the length of the provided buffer.
7365

7466
### Usage as Queue
7567

7668
```go
77-
dq := blocking_dequeue.NewBlockingDequeue[int]()
69+
buffer := make([]int, 10)
70+
dq := blocking_dequeue.NewBlockingDequeue(buffer)
7871

7972
dq.PushBack(1) // Pushed to the end of the dequeue
8073
dq.PushBack(2) // Pushed to the end of the dequeue
@@ -88,7 +81,8 @@ dq.PopFront() // Pops from the top, returns 3
8881
### Usage as Stack
8982

9083
```go
91-
dq := blocking_dequeue.NewBlockingDequeue[int]()
84+
buffer := make([]int, 10)
85+
dq := blocking_dequeue.NewBlockingDequeue(buffer)
9286

9387
dq.PushFront(1) // Pushed to the start of the dequeue
9488
dq.PushFront(2) // Pushed to the start of the dequeue
@@ -108,22 +102,21 @@ The dequeue itself exposes the following methods:
108102
- `PushFront`, `PushBack`
109103
- `PopFront`, `PopBack`
110104
- `PeekFront`, `PeekBack`
111-
- `Capacity`, `SetCapacity`, `IsFull`
112-
- `Size`, `IsEmpty`
105+
- `Size`, `IsEmpty`, `IsFull`
113106

114107
The detailed documentation can be found at the related [go packages page](https://pkg.go.dev/github.com/AmrSaber/go-blocking-dequeue#section-documentation).
115108

116109
## Limitations and Drawbacks
117110

118-
This dequeue is implemented using build-in `container/list` so all of the operations are done in O(1) time complexity.
111+
This dequeue is implemented using ring (or circular) buffer so all of the operations are done in O(1) time complexity.
119112

120-
However, due to the thread-safe nature, and all the lock/unlock/wait/signal/broadcast logic, it's expected to be a bit slower than the plain `container/list`. 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 the built-in `container/list` instead.
113+
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.
121114

122115
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
123116

124117
```go
125-
dq := blocking_dequeue.NewBlockingDequeue[int]()
126-
dq.SetCapacity(10)
118+
buffer := make([]int, 10)
119+
dq := blocking_dequeue.NewBlockingDequeue(buffer)
127120

128121
// Push to queue
129122
dq.PushBack(1)
@@ -148,7 +141,7 @@ That is unless you need access the other provided methods, such as `Peek` variat
148141

149142
## Benchmarking
150143

151-
No benchmarking against the built-in `container/list` nor channels yet. But it's in the plan.
144+
No benchmarking against plain ring buffer or the built-in `container/list` nor channels yet. But it's in the plan.
152145

153146
## Contribution
154147

0 commit comments

Comments
 (0)