goconcurrentqueue

https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue
Admin
goconcurrentqueue provides concurrent-safe queue implementations in Go that can be used concurrently...
Tokens:2,968
Snippets:45
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install goconcurrentqueue

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Command to install the package via go get.

```bash
go get github.com/enriquebris/goconcurrentqueue
```

--------------------------------

### Get QueueError Code

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Returns the error code string.

```go
func (st *QueueError) Code() string
```

--------------------------------

### Get QueueError Message

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Returns the error message string.

```go
func (st *QueueError) Error() string
```

--------------------------------

### Get FixedFIFO Capacity

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Returns the maximum capacity of the queue.

```go
func (st *FixedFIFO) GetCap() int
```

--------------------------------

### Get FixedFIFO Length

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Returns the current number of elements in the queue.

```go
func (st *FixedFIFO) GetLen() int
```

--------------------------------

### Dependency Inversion with Queues

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Shows how to use the Queue interface to decouple implementation details from business logic.

```go
package main

import (
	"fmt"

	"github.com/enriquebris/goconcurrentqueue"
)

func main() {
	var (
		queue          goconcurrentqueue.Queue
		dummyCondition = true
	)

	// decides which Queue's implementation is the best option for this scenario
	if dummyCondition {
		queue = goconcurrentqueue.NewFIFO()
	} else {
		queue = goconcurrentqueue.NewFixedFIFO(10)
	}

	fmt.Printf("queue's length: %v\n", queue.GetLen())
	workWithQueue(queue)
	fmt.Printf("queue's length: %v\n", queue.GetLen())
}

// workWithQueue uses a goconcurrentqueue.Queue to perform the work
func workWithQueue(queue goconcurrentqueue.Queue) error {
	// do some work

	// enqueue an item
	if err := queue.Enqueue("test value"); err != nil {
		return err
	}

	return nil
}
```

--------------------------------

### FIFO Queue Basic Usage

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Demonstrates initializing a FIFO queue, enqueuing various types, and dequeuing items.

```go
package main

import (
	"fmt"

	"github.com/enriquebris/goconcurrentqueue"
)

type AnyStruct struct {
	Field1 string
	Field2 int
}

func main() {
	queue := goconcurrentqueue.NewFIFO()

	queue.Enqueue("any string value")
	queue.Enqueue(5)
	queue.Enqueue(AnyStruct{Field1: "hello world", Field2: 15})

	// will output: 3
	fmt.Printf("queue's length: %v\n", queue.GetLen())

	item, err := queue.Dequeue()
	if err != nil {
		fmt.Println(err)
		return
	}

	// will output "any string value"
	fmt.Printf("dequeued item: %v\n", item)

	// will output: 2
	fmt.Printf("queue's length: %v\n", queue.GetLen())

}
```

--------------------------------

### Initialize FIFO Queue

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Constructor for creating a new FIFO queue instance.

```go
func NewFIFO() *FIFO
```

--------------------------------

### Initialize FixedFIFO

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Creates a new FixedFIFO instance with the specified capacity.

```go
func NewFixedFIFO(capacity int) *FixedFIFO
```

--------------------------------

### FIFO Queue Management Methods

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Methods for adding elements, inspecting queue state, and accessing elements by index.

```go
func (st *FIFO) Enqueue(value interface{}) error
```

```go
func (st *FIFO) Get(index int) (interface{}, error)
```

```go
func (st *FIFO) GetCap() int
```

```go
func (st *FIFO) GetLen() int
```

--------------------------------

### Create New QueueError

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Initializes a new QueueError with a code and message.

```go
func NewQueueError(code string, message string) *QueueError
```

--------------------------------

### Queue Interface Definition

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Defines the standard operations for concurrent queue implementations.

```go
type Queue interface {
	// Enqueue element
	Enqueue(interface{}) error
	// Dequeue element
	Dequeue() (interface{}, error)
	// DequeueOrWaitForNextElement dequeues an element (if exist) or waits until the next element gets enqueued and returns it.
	// Multiple calls to DequeueOrWaitForNextElement() would enqueue multiple "listeners" for future enqueued elements.
	DequeueOrWaitForNextElement() (interface{}, error)
	// DequeueOrWaitForNextElementContext dequeues an element (if exist) or waits until the next element gets enqueued and returns it.
	// Multiple calls to DequeueOrWaitForNextElementContext() would enqueue multiple "listeners" for future enqueued elements.
	// When the passed context expires this function exits and returns the context' error
	DequeueOrWaitForNextElementContext(context.Context) (interface{}, error)
	// Get number of enqueued elements
	GetLen() int
	// Get queue's capacity
	GetCap() int

	// Lock the queue. No enqueue/dequeue/remove/get operations will be allowed after this point.
	Lock()
	// Unlock the queue.
	Unlock()
	// Return true whether the queue is locked
	IsLocked() bool
}
```

--------------------------------

### Dequeue or Wait for Element

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Blocks until an element is available in the queue.

```go
func (st *FixedFIFO) DequeueOrWaitForNextElement() (interface{}, error)
```

--------------------------------

### Dequeue or Wait with Context

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Blocks until an element is available or the provided context expires.

```go
func (st *FixedFIFO) DequeueOrWaitForNextElementContext(ctx context.Context) (interface{}, error)
```

--------------------------------

### func NewFIFO() *FIFO

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Initializes and returns a new FIFO concurrent queue instance.

```APIDOC
## func NewFIFO()

### Description
Returns a new FIFO concurrent queue.

### Signature
`func NewFIFO() *FIFO`
```

--------------------------------

### Enqueue to FixedFIFO

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Adds an element to the queue, returning an error if locked or at full capacity.

```go
func (st *FixedFIFO) Enqueue(value interface{}) error
```

--------------------------------

### Wait for Element with Timeout

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Uses a context to wait for an element with a specified timeout duration.

```go
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/enriquebris/goconcurrentqueue"
)

func main() {
	var (
		fifo = goconcurrentqueue.NewFIFO()
		ctx, cancel = context.WithTimeout(context.Background(), 3*time.Second)
	)
	defer cancel()

	fmt.Println("1 - Waiting for next enqueued element")
	_, err := fifo.DequeueOrWaitForNextElementContext(ctx)
    
	if err != nil {
		fmt.Printf("2 - Failed waiting for new element: %v\n", err)
		return
	}
}
```

--------------------------------

### FIFO Queue Structure

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

The primary FIFO concurrent queue structure.

```go
type FIFO struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### FIFO Dequeue Operations

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Methods for retrieving elements from the FIFO queue, including blocking and context-aware variants.

```go
func (st *FIFO) Dequeue() (interface{}, error)
```

```go
func (st *FIFO) DequeueOrWaitForNextElement() (interface{}, error)
```

```go
func (st *FIFO) DequeueOrWaitForNextElementContext(ctx context.Context) (interface{}, error)
```

--------------------------------

### Queue Error Constants

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Standard error codes used by the queue implementation to indicate specific failure states.

```go
const (
	QueueErrorCodeEmptyQueue            = "empty-queue"
	QueueErrorCodeLockedQueue           = "locked-queue"
	QueueErrorCodeIndexOutOfBounds      = "index-out-of-bounds"
	QueueErrorCodeFullCapacity          = "full-capacity"
	QueueErrorCodeInternalChannelClosed = "internal-channel-closed"
)
```

--------------------------------

### Dequeue from FixedFIFO

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Dequeues an element, returning an error if the queue is locked, empty, or closed.

```go
func (st *FixedFIFO) Dequeue() (interface{}, error)
```

--------------------------------

### FixedFIFO Structure Definition

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Represents a fixed-capacity concurrent FIFO queue.

```go
type FixedFIFO struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### Wait Channel Capacity Constant

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Defines the buffer size for the internal channel used in blocking dequeue operations.

```go
const (
	WaitForNextElementChanCapacity = 1000
)
```

--------------------------------

### QueueError Structure

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Custom error type for queue-related operations.

```go
type QueueError struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### Unlock FixedFIFO Queue

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Unlocks the FixedFIFO queue.

```go
func (st *FixedFIFO) Unlock()
```

--------------------------------

### func (*FIFO) Enqueue(value interface{}) error

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Enqueues an element into the FIFO queue. Returns an error if the queue is locked.

```APIDOC
## func (*FIFO) Enqueue()

### Description
Enqueues an element. Returns error if queue is locked.

### Signature
`func (st *FIFO) Enqueue(value interface{}) error`
```

--------------------------------

### Check FixedFIFO Lock Status

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Returns true if the FixedFIFO queue is locked.

```go
func (st *FixedFIFO) IsLocked() bool
```

--------------------------------

### func (*FIFO) DequeueOrWaitForNextElementContext(ctx context.Context) (interface{}, error)

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Dequeues an element or waits until the next element is enqueued, respecting the provided context for cancellation.

```APIDOC
## func (*FIFO) DequeueOrWaitForNextElementContext()

### Description
Dequeues an element (if exist) or waits until the next element gets enqueued and returns it. When the passed context expires this function exits and returns the context' error.

### Signature
`func (st *FIFO) DequeueOrWaitForNextElementContext(ctx context.Context) (interface{}, error)`
```

--------------------------------

### Unlock FIFO Queue

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Unlocks the queue to allow operations again.

```go
func (st *FIFO) Unlock()
```

--------------------------------

### Wait for Enqueued Element

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Blocks execution until an element is available in the queue using DequeueOrWaitForNextElement.

```go
package main

import (
	"fmt"
	"time"

	"github.com/enriquebris/goconcurrentqueue"
)

func main() {
	var (
		fifo = goconcurrentqueue.NewFIFO()
		done = make(chan struct{})
	)

	go func() {
		fmt.Println("1 - Waiting for next enqueued element")
		value, _ := fifo.DequeueOrWaitForNextElement()
		fmt.Printf("2 - Dequeued element: %v\n", value)

		done <- struct{}{}
	}()

	fmt.Println("3 - Go to sleep for 3 seconds")
	time.Sleep(3 * time.Second)

	fmt.Println("4 - Enqueue element")
	fifo.Enqueue(100)

	<-done
}
```

--------------------------------

### func (*FIFO) Dequeue() (interface{}, error)

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Dequeues an element from the FIFO queue. Returns an error if the queue is locked or empty.

```APIDOC
## func (*FIFO) Dequeue()

### Description
Dequeues an element. Returns error if queue is locked or empty.

### Signature
`func (st *FIFO) Dequeue() (interface{}, error)`
```

--------------------------------

### Check FIFO Lock Status

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Returns true if the FIFO queue is currently locked.

```go
func (st *FIFO) IsLocked() bool
```

--------------------------------

### func (*FIFO) DequeueOrWaitForNextElement() (interface{}, error)

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Dequeues an element if available, otherwise blocks until the next element is enqueued.

```APIDOC
## func (*FIFO) DequeueOrWaitForNextElement()

### Description
Dequeues an element (if exist) or waits until the next element gets enqueued and returns it. Multiple calls to DequeueOrWaitForNextElement() would enqueue multiple "listeners" for future enqueued elements.

### Signature
`func (st *FIFO) DequeueOrWaitForNextElement() (interface{}, error)`
```

--------------------------------

### Remove Element from FIFO

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Removes an element at the specified index from the queue.

```go
func (st *FIFO) Remove(index int) error
```

--------------------------------

### Lock FixedFIFO Queue

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Locks the FixedFIFO queue.

```go
func (st *FixedFIFO) Lock()
```

--------------------------------

### Lock FIFO Queue

Source: https://pkg.go.dev/github.com/enriquebris/goconcurrentqueue

Locks the queue, preventing further enqueue or dequeue operations.

```go
func (st *FIFO) Lock()
```
Tokens:
Raw