PCQ(9)

PCQ(9) | Kernel Developer's Manual | PCQ(9)

# NAME

pcq — producer/consumer queue

# SYNOPSIS

#include <sys/pcq.h>
pcq_t *
pcq_create(size_t maxlen, km_flags_t kmflags);
void
pcq_destroy(pcq_t *pcq);
void *
pcq_get(pcq_t *pcq);
size_t
pcq_maxitems(pcq_t *pcq);
void *
pcq_peek(pcq_t *pcq);
bool
pcq_put(pcq_t *pcq, void *item);

# DESCRIPTION

The machine-independent pcq interface provides lockless producer/consumer queues. A queue (pcq_t) allows multiple writers (producers), but only a single reader (consumer). The consumer is expected to be protected by a lock that covers the structure that the pcq_t is embedded into (e.g., socket lock, ifnet hwlock). These queues operate in a first-in, first-out (FIFO) manner. The act of inserting or removing an item from a pcq_t does not modify the item in any way. pcq does not prevent an item from being inserted multiple times into a single pcq_t.

# FUNCTIONS

pcq_create(maxlen, kmflags)
  Create a queue that can store at most maxlen items at one time. kmflags should be either `KM_SLEEP`, if pcq_create() is allowed to sleep until resources are available, or `KM_NOSLEEP` if it should return `NULL` immediately, if resources are unavailable.
pcq_destroy(pcq)
  Free the resources held by pcq.
pcq_get(pcq)
  Remove the next item to be consumed from the queue and return it. If the queue is empty, return `NULL`. The caller must prevent concurrent gets from occuring.
pcq_maxitems(pcq)
  Return the maximum number of items that the queue can store at any one time.
pcq_peek(pcq)
  Return the next item to be consumed from the queue but do not remove it from the queue. If the queue is empty, return `NULL`.
pcq_put(pcq, item)
  Place an item at the end of the queue. If there is no room in the queue for the item, return `false`; otherwise, return `true`. The item must not have the value of `NULL`.

# CODE REFERENCES

The pcq interface is implemented within the file sys/kern/subr_pcq.c.

# SEE ALSO

atomic_ops(3), queue(3)

# HISTORY

The pcq interface first appeared in NetBSD 6.0.

January 22, 2012 | NetBSD 8.3