December 26, 2005 BUFQ 9

### NAME

bufq, bufq_state, bufq_alloc, bufq_drain, bufq_free, bufq_getstrategyname, bufq_move, BUFQ_PUT, BUFQ_GET, BUFQ_PEEK, BUFQ_CANCEL - device buffer queues

### SYNOPSIS

```int` bufq_alloc(```struct bufq_state **bufq``, const char *strategy``, int flags`)
```void` bufq_drain(```struct bufq_state *bufq`)
```void` bufq_free(```struct bufq_state *bufq`)
```const char *` bufq_getstrategyname(```struct bufq_state *bufq`)
```void` bufq_move(```struct bufq_state *dst``, struct bufq_state *src`)
```void` BUFQ_PUT(```struct bufq_state *bufq``, struct buf *bp`)
```struct buf *` BUFQ_GET(```struct bufq_state *bufq`)
```struct buf *` BUFQ_PEEK(```struct bufq_state *bufq`)
```struct buf *` BUFQ_CANCEL(```struct bufq_state *bufq``, struct buf *bp`)

### DESCRIPTION

The bufq subsystem is a set of operations for the management of device buffer queues.

The primary data type for using the operations is the bufq_state structure, which is opaque for users.

### FUNCTIONS

bufq_alloc(```bufq``, strategy``, flags`)
  Allocate and initialize a bufq_state descriptor.

  The argument ```strategy` specifies a buffer queue strategy to be used for this buffer queue. The following special values can be used:

  ```BUFQ_STRAT_ANY`
    Let bufq_alloc(``) select a strategy.
  ```BUFQ_DISK_DEFAULT_STRAT`
    Let bufq_alloc(``) select a strategy, assuming it will be used for a normal disk device.

  Valid bits for the ```flags` are:

  ```BUFQ_SORT_RAWBLOCK`
    sort by b_rawblkno
  ```BUFQ_SORT_CYLINDER`
    sort by b_cylinder and then by b_rawblkno
  ```BUFQ_EXACT`
    Fail if a strategy specified by ```strategy` is not available. In that case, ```bufq_alloc` returns ```ENOENT`. If this flag is not specified, bufq_alloc(``) will silently use one of available strategies.

bufq_drain(```bufq`)
  Drain a bufq_state descriptor.

bufq_free(```bufq`)
  Destroy a bufq_state descriptor.

bufq_getstrategyname(```bufq`)
  Get a strategy identifier of a buffer queue, the string returned will be NUL-terminated and it always will be a valid strategy name.

bufq_move(```dst``, src`)
  Move all requests from the buffer queue ```src` to the buffer queue ```dst`.

BUFQ_PUT(```bufq``, bp`)
  Put the buf ```bp` in the queue.

BUFQ_GET(```bufq`)
  Get the next buf from the queue and remove it from the queue. Returns ```NULL` if the queue is empty.

BUFQ_PEEK(```bufq`)
  Get the next buf from the queue without removal. The next buf will remain the same until BUFQ_GET(``), BUFQ_PUT(``), or bufq_drain(``) is called. Returns ```NULL` if the queue is empty.

BUFQ_CANCEL(```bufq``, bp`)
  Cancel the buf ```bp` issued earlier on the queue. Returns ```NULL` if the element can not be found on the queue or ```bp` if it has been found and removed.

### CODE REFERENCES

The actual code implementing the device buffer queues can be found in the file ```sys/kern/subr_bufq.c`.

### HISTORY

The bufq subsystem appeared in NetBSD2.0.

### AUTHORS

The bufq subsystem was written by Juergen Hannken-Illjes
<hannken@NetBSD.org>.