queue

Documentation

Overview

Package queue provides Vault plugins with a Priority Queue. It can be used as an in-memory list of queue.Item sorted by their priority, and offers methods to find or remove items by their key. Internally it uses container/heap; see Example Priority Queue: https://golang.org/pkg/container/heap/#example__priorityQueue

Index

• Variables
• type Item
• type PriorityQueue
  • func New() *PriorityQueue
  • func (pq *PriorityQueue) Len() int
  • func (pq *PriorityQueue) Pop() (*Item, error)
  • func (pq *PriorityQueue) PopByKey(key string) (*Item, error)
  • func (pq *PriorityQueue) Push(i *Item) error
  • func (pq *PriorityQueue) RetrieveByKey(key string) *Item

Variables

var ErrDuplicateItem = errors.New("duplicate item")

ErrDuplicateItem is returned when the queue attempts to push an item to a key that already exists. The queue does not attempt to update, instead returns this error. If an Item needs to be updated or replaced, pop the item first.

var ErrEmpty = errors.New("queue is empty")

ErrEmpty is returned for queues with no items

Types

type Item

type Item struct {
	// Key is a unique string used to identify items in the internal data map
	Key string
	// Value is an unspecified type that implementations can use to store
	// information
	Value interface{}

	// Priority determines ordering in the queue, with the lowest value being the
	// highest priority
	Priority int64
	// contains filtered or unexported fields
}

Item is something managed in the priority queue

type PriorityQueue

type PriorityQueue struct {
	// contains filtered or unexported fields
}

PriorityQueue facilitates queue of Items, providing Push, Pop, and PopByKey convenience methods. The ordering (priority) is an int64 value with the smallest value is the highest priority. PriorityQueue maintains both an internal slice for the queue as well as a map of the same items with their keys as the index. This enables users to find specific items by key. The map must be kept in sync with the data slice. See https://golang.org/pkg/container/heap/#example__priorityQueue

func New

func New() *PriorityQueue

New initializes the internal data structures and returns a new PriorityQueue

func (*PriorityQueue) Len

func (pq *PriorityQueue) Len() int

Len returns the count of items in the Priority Queue

func (*PriorityQueue) Pop

func (pq *PriorityQueue) Pop() (*Item, error)

Pop pops the highest priority item from the queue. This is a wrapper/convenience method that calls heap.Pop, so consumers do not need to invoke heap functions directly

func (*PriorityQueue) PopByKey

func (pq *PriorityQueue) PopByKey(key string) (*Item, error)

PopByKey searches the queue for an item with the given key and removes it from the queue if found. Returns nil if not found. This method must fix the queue after removing any key.

func (*PriorityQueue) Push

func (pq *PriorityQueue) Push(i *Item) error

Push pushes an item on to the queue. This is a wrapper/convenience method that calls heap.Push, so consumers do not need to invoke heap functions directly. Items must have unique Keys, and Items in the queue cannot be updated. To modify an Item, users must first remove it and re-push it after modifications. Item does not get copied before pushing on to the queue, it's up to the caller to copy the item.

func (*PriorityQueue) RetrieveByKey

func (pq *PriorityQueue) RetrieveByKey(key string) *Item

RetrieveByKey searches the queue for an item with the given key and returns it from the queue if found. Returns nil if not found.