v2.0.0
Functions
queue
High Level APIs » pico_util

Multi-core and IRQ safe queue implementation. More...

## Functions
void | queue_init_with_spinlock (queue_t *q, uint element_size, uint element_count, uint spinlock_num)
| Initialise a queue with a specific spinlock for concurrency protection. More...
static void | queue_init (queue_t *q, uint element_size, uint element_count)
| Initialise a queue, allocating a (possibly shared) spinlock. More...
void | queue_free (queue_t *q)
| Destroy the specified queue. More...
static uint | queue_get_level_unsafe (queue_t *q)
| Unsafe check of level of the specified queue. More...
static uint | queue_get_level (queue_t *q)
| Check of level of the specified queue. More...
static bool | queue_is_empty (queue_t *q)
| Check if queue is empty. More...
static bool | queue_is_full (queue_t *q)
| Check if queue is full. More...
bool | queue_try_add (queue_t *q, const void *data)
| Non-blocking add value queue if not full. More...
bool | queue_try_remove (queue_t *q, void *data)
| Non-blocking removal of entry from the queue if non empty. More...
bool | queue_try_peek (queue_t *q, void *data)
| Non-blocking peek at the next item to be removed from the queue. More...
void | queue_add_blocking (queue_t *q, const void *data)
| Blocking add of value to queue. More...
void | queue_remove_blocking (queue_t *q, void *data)
| Blocking remove entry from queue. More...
void | queue_peek_blocking (queue_t *q, void *data)
| Blocking peek at next value to be removed from queue. More...

## Detailed Description

Multi-core and IRQ safe queue implementation.

Note that this queue stores values of a specified size, and pushed values are copied into the queue

## Function Documentation

## ◆ queue_add_blocking()

void queue_add_blocking | ( | queue_t * | q,
|  | const void * | data
| ) |  |

Blocking add of value to queue.

Parameters

  q | Pointer to a queue_t structure, used as a handle
  data | Pointer to value to be copied into the queue

If the queue is full this function will block, until a removal happens on the queue

## ◆ queue_free()

void queue_free | ( | queue_t * | q | ) |

Destroy the specified queue.

Parameters

  q | Pointer to a queue_t structure, used as a handle

Does not deallocate the queue_t structure itself.

## ◆ queue_get_level()

static uint queue_get_level | ( | queue_t * | q | ) |
| inlinestatic

Check of level of the specified queue.

Parameters

  q | Pointer to a queue_t structure, used as a handle

Returns
  Number of entries in the queue

## ◆ queue_get_level_unsafe()

static uint queue_get_level_unsafe | ( | queue_t * | q | ) |
| inlinestatic

Unsafe check of level of the specified queue.

Parameters

  q | Pointer to a queue_t structure, used as a handle

Returns
  Number of entries in the queue

This does not use the spinlock, so may return incorrect results if the spin lock is not externally locked

## ◆ queue_init()

static void queue_init | ( | queue_t * | q,
|  | uint | element_size,
|  | uint | element_count
| ) |  |
| inlinestatic

Initialise a queue, allocating a (possibly shared) spinlock.

Parameters

  q | Pointer to a queue_t structure, used as a handle
  element_size | Size of each value in the queue
  element_count | Maximum number of entries in the queue

## ◆ queue_init_with_spinlock()

void queue_init_with_spinlock | ( | queue_t * | q,
|  | uint | element_size,
|  | uint | element_count,
|  | uint | spinlock_num
| ) |  |

Initialise a queue with a specific spinlock for concurrency protection.

Parameters

  q | Pointer to a queue_t structure, used as a handle
  element_size | Size of each value in the queue
  element_count | Maximum number of entries in the queue
  spinlock_num | The spin ID used to protect the queue

## ◆ queue_is_empty()

static bool queue_is_empty | ( | queue_t * | q | ) |
| inlinestatic

Check if queue is empty.

Parameters

  q | Pointer to a queue_t structure, used as a handle

Returns
  true if queue is empty, false otherwise

This function is interrupt and multicore safe.

## ◆ queue_is_full()

static bool queue_is_full | ( | queue_t * | q | ) |
| inlinestatic

Check if queue is full.

Parameters

  q | Pointer to a queue_t structure, used as a handle

Returns
  true if queue is full, false otherwise

This function is interrupt and multicore safe.

## ◆ queue_peek_blocking()

void queue_peek_blocking | ( | queue_t * | q,
|  | void * | data
| ) |  |

Blocking peek at next value to be removed from queue.

Parameters

  q | Pointer to a queue_t structure, used as a handle
  data | Pointer to the location to receive the peeked value, or NULL if the data isn't required

If the queue is empty function will block until a value is added

## ◆ queue_remove_blocking()

void queue_remove_blocking | ( | queue_t * | q,
|  | void * | data
| ) |  |

Blocking remove entry from queue.

Parameters

  q | Pointer to a queue_t structure, used as a handle
  data | Pointer to the location to receive the removed value, or NULL if the data isn't required

If the queue is empty this function will block until a value is added.

## ◆ queue_try_add()

bool queue_try_add | ( | queue_t * | q,
|  | const void * | data
| ) |  |

Non-blocking add value queue if not full.

Parameters

  q | Pointer to a queue_t structure, used as a handle
  data | Pointer to value to be copied into the queue

Returns
  true if the value was added

If the queue is full this function will return immediately with false, otherwise the data is copied into a new value added to the queue, and this function will return true.

## ◆ queue_try_peek()

bool queue_try_peek | ( | queue_t * | q,
|  | void * | data
| ) |  |

Non-blocking peek at the next item to be removed from the queue.

Parameters

  q | Pointer to a queue_t structure, used as a handle
  data | Pointer to the location to receive the peeked value, or NULL if the data isn't required

Returns
  true if there was a value to peek

If the queue is not empty this function will return immediately with true with the peeked entry copied into the location specified by the data parameter, otherwise the function will return false.

## ◆ queue_try_remove()

bool queue_try_remove | ( | queue_t * | q,
|  | void * | data
| ) |  |

Non-blocking removal of entry from the queue if non empty.

Parameters

  q | Pointer to a queue_t structure, used as a handle
  data | Pointer to the location to receive the removed value, or NULL if the data isn't required

Returns
  true if a value was removed

If the queue is not empty function will copy the removed value into the location provided and return immediately with true, otherwise the function will return immediately with false.