---
name: "coveb"
section: "3"
platform: "linux"
package: "libcoveb1"
version: "1.0.4-1"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/coveb"
---

# coveb(3)

cache oblivious high speed 32-bit priority queue for large data sets

## NAME

coveb - cache oblivious high speed 32-bit priority queue for large data sets

## SYNOPSIS

**coveb :** library for space and time efficient manipulation of unsigned 32-bit integers.

## DESCRIPTION

**please see coveb-tree.h or the included README for details.**

- **#include \<coveb.h\>**

  Instantiation:

- **struct coveb\_bq \*q;**

  - **q = coveb\_bq\_new();**

  - This allocates a new cache-oblivious bitwise priority queue. To free, use:

  - **Deallocation:**

  - **coveb\_bq\_free(q);**

  - **Insertion of 32-bit unsigned integer values:**

  - **void coveb\_bq\_insert(struct coveb\_bq \*q, uint32\_t x);**

  - places a new value into the queue, or does nothing if it's already there.

  - **Removal of values:**

  - **uint32\_t coveb\_bq\_extractmin(struct coveb\_bq \*q);**

  - removes the smallest value (min) from the queue and returns it. It is illegal to try to remove a value from an empty (size = 0) queue. This is the fastest way to remove elements.

  - **uint32\_t coveb\_bq\_remove(struct coveb\_bq \*q, uint32\_t x);**

  - This generic function removes any specific value from the queue. It returns 0 if the object was already in the queue, and 1 if not.

  - Queue status monitoring:

  - When the queue is completely full (containing four 'binary' gigasamples), it consumes about one gigabyte of memory. This means that it uses about 2 bits per sample on average when full. This is only about twice as big as the literal storage cost of a typical queue state. Because this size is not reportable as a 32-bit integer, the following function is available to detect the full queue condition:

  - **uint32\_t coveb\_bq\_addresses\_full(const struct coveb\_bq \*q);**

  - Returns 1 if all 2 \*\* 32 elements are in the queue, or 0 otherwise. When the queue is not full, the normal size function is exactly accurate:

  - **uint32\_t coveb\_bq\_size(const struct coveb\_bq \*q);**

  - returns the count of integers currently stored in the queue. This can be used to see if an element can be extracted safely (size \> 0). Note that in the special case where the queue is completely full and therefore the number of elements in the queue is one greater than the maximum value of an unsigned 32-bit integer, the size function will return instead one less than the actual number of elements. To detect this uncommon condition use coveb\_bq\_addresses\_full.

  - **Extrema functions**

  - **uint32\_t coveb\_bq\_max(const struct coveb\_bq \*q);**

  - returns the largest integer stored in the queue without removal.

  - **uint32\_t coveb\_bq\_min(const struct coveb\_bq \*q);**

  - returns the smallest integer stored in the queue without removal.

  - **Rangefinding functions**

  - **void coveb\_bq\_locate\_smallest\_not\_less\_than(const struct coveb\_bq \*q, uint32\_t incl\_lower\_bound, uint32\_t \*result\_x, uint32\_t \*gotresult);**

  - searches for an integer stored in the queue that is not less than incl\_lower\_bound. If there is more than one such integer, the smallest is returned. If an integer is found, \*gotresult will be set to 1 and \*result\_x will hold the integer that was found. If no such integer is found in the queue, then \*gotresult with be set to 0 and \*result\_x will be untouched. The queue is not modified in any case.

  - **void coveb\_bq\_successor(const struct coveb\_bq \*q, uint32\_t excl\_lower\_bound, uint32\_t \*result\_x, uint32\_t \*gotresult);**

  - This function scans upward for an integer that is greater than excl\_lower\_bound. It is otherwise the same as the coveb\_bq\_locate\_smallest\_not\_less\_than function.

  - This library uses a data structure inspired by Peter van Emde Boas.

  - none

  ## ENVIRONMENT

## DIAGNOSTICS

The failout(msg) macro may be redefined using #define FAILOUT\_FUNC(msg)

## SEE ALSO