JACK-AUDIO-CONNECTION-KIT: ringbuffer.h File Reference

# ringbuffer.h File Reference

`#include <sys/types.h>`

Go to the source code of this file.

## Data Structures
struct | jack_ringbuffer_data_t
struct | jack_ringbuffer_t
## Functions
jack_ringbuffer_t * | jack_ringbuffer_create (size_t sz)
void | jack_ringbuffer_free (jack_ringbuffer_t *rb)
void | jack_ringbuffer_get_read_vector (const jack_ringbuffer_t *rb, jack_ringbuffer_data_t *vec)
void | jack_ringbuffer_get_write_vector (const jack_ringbuffer_t *rb, jack_ringbuffer_data_t *vec)
size_t | jack_ringbuffer_read (jack_ringbuffer_t *rb, char *dest, size_t cnt)
size_t | jack_ringbuffer_peek (jack_ringbuffer_t *rb, char *dest, size_t cnt)
void | jack_ringbuffer_read_advance (jack_ringbuffer_t *rb, size_t cnt)
size_t | jack_ringbuffer_read_space (const jack_ringbuffer_t *rb)
int | jack_ringbuffer_mlock (jack_ringbuffer_t *rb)
void | jack_ringbuffer_reset (jack_ringbuffer_t *rb)
size_t | jack_ringbuffer_write (jack_ringbuffer_t *rb, const char *src, size_t cnt)
void | jack_ringbuffer_write_advance (jack_ringbuffer_t *rb, size_t cnt)
size_t | jack_ringbuffer_write_space (const jack_ringbuffer_t *rb)

## Detailed Description

A set of library functions to make lock-free ringbuffers available to JACK clients. The `capture_client.c' (in the example_clients directory) is a fully functioning user of this API.

The key attribute of a ringbuffer is that it can be safely accessed by two threads simultaneously -- one reading from the buffer and the other writing to it -- without using any synchronization or mutual exclusion primitives. For this to work correctly, there can only be a single reader and a single writer thread. Their identities cannot be interchanged.

## Function Documentation

jack_ringbuffer_t* jack_ringbuffer_create | ( | size_t | sz | ) |

Allocates a ringbuffer data structure of a specified size. The caller must arrange for a call to jack_ringbuffer_free() to release the memory associated with the ringbuffer.

Parameters:

  | sz | the ringbuffer size in bytes.

Returns:
  a pointer to a new jack_ringbuffer_t, if successful; NULL otherwise.

void jack_ringbuffer_free | ( | jack_ringbuffer_t * | rb | ) |

Frees the ringbuffer data structure allocated by an earlier call to jack_ringbuffer_create().

Parameters:

  | rb | a pointer to the ringbuffer structure.

void jack_ringbuffer_get_read_vector | ( | const jack_ringbuffer_t * | rb,
|  | jack_ringbuffer_data_t * | vec |
| ) |  |  |

Fill a data structure with a description of the current readable data held in the ringbuffer. This description is returned in a two element array of jack_ringbuffer_data_t. Two elements are needed because the data to be read may be split across the end of the ringbuffer.

The first element will always contain a valid len field, which may be zero or greater. If the len field is non-zero, then data can be read in a contiguous fashion using the address given in the corresponding buf field.

If the second element has a non-zero len field, then a second contiguous stretch of data can be read from the address given in its corresponding buf field.

Parameters:

  | rb | a pointer to the ringbuffer structure.
  | vec | a pointer to a 2 element array of jack_ringbuffer_data_t.

void jack_ringbuffer_get_write_vector | ( | const jack_ringbuffer_t * | rb,
|  | jack_ringbuffer_data_t * | vec |
| ) |  |  |

Fill a data structure with a description of the current writable space in the ringbuffer. The description is returned in a two element array of jack_ringbuffer_data_t. Two elements are needed because the space available for writing may be split across the end of the ringbuffer.

The first element will always contain a valid len field, which may be zero or greater. If the len field is non-zero, then data can be written in a contiguous fashion using the address given in the corresponding buf field.

If the second element has a non-zero len field, then a second contiguous stretch of data can be written to the address given in the corresponding buf field.

Parameters:

  | rb | a pointer to the ringbuffer structure.
  | vec | a pointer to a 2 element array of jack_ringbuffer_data_t.

int jack_ringbuffer_mlock | ( | jack_ringbuffer_t * | rb | ) |

Lock a ringbuffer data block into memory.

Uses the mlock() system call. This is not a realtime operation.

Parameters:

  | rb | a pointer to the ringbuffer structure.

size_t jack_ringbuffer_peek | ( | jack_ringbuffer_t * | rb,
|  | char * | dest,
|  | size_t | cnt |
| ) |  |  |

Read data from the ringbuffer. Opposed to jack_ringbuffer_read() this function does not move the read pointer. Thus it's a convenient way to inspect data in the ringbuffer in a continous fashion. The price is that the data is copied into a user provided buffer. For "raw" non-copy inspection of the data in the ringbuffer use jack_ringbuffer_get_read_vector().

Parameters:

  | rb | a pointer to the ringbuffer structure.
  | dest | a pointer to a buffer where data read from the ringbuffer will go.
  | cnt | the number of bytes to read.

Returns:
  the number of bytes read, which may range from 0 to cnt.

size_t jack_ringbuffer_read | ( | jack_ringbuffer_t * | rb,
|  | char * | dest,
|  | size_t | cnt |
| ) |  |  |

Read data from the ringbuffer.

Parameters:

  | rb | a pointer to the ringbuffer structure.
  | dest | a pointer to a buffer where data read from the ringbuffer will go.
  | cnt | the number of bytes to read.

Returns:
  the number of bytes read, which may range from 0 to cnt.

void jack_ringbuffer_read_advance | ( | jack_ringbuffer_t * | rb,
|  | size_t | cnt |
| ) |  |  |

Advance the read pointer.

After data have been read from the ringbuffer using the pointers returned by jack_ringbuffer_get_read_vector(), use this function to advance the buffer pointers, making that space available for future write operations.

Parameters:

  | rb | a pointer to the ringbuffer structure.
  | cnt | the number of bytes read.

size_t jack_ringbuffer_read_space | ( | const jack_ringbuffer_t * | rb | ) |

Return the number of bytes available for reading.

Parameters:

  | rb | a pointer to the ringbuffer structure.

Returns:
  the number of bytes available to read.

void jack_ringbuffer_reset | ( | jack_ringbuffer_t * | rb | ) |

Reset the read and write pointers, making an empty buffer.

This is not thread safe.

Parameters:

  | rb | a pointer to the ringbuffer structure.

size_t jack_ringbuffer_write | ( | jack_ringbuffer_t * | rb,
|  | const char * | src,
|  | size_t | cnt |
| ) |  |  |

Write data into the ringbuffer.

Parameters:

  | rb | a pointer to the ringbuffer structure.
  | src | a pointer to the data to be written to the ringbuffer.
  | cnt | the number of bytes to write.

Returns:
  the number of bytes write, which may range from 0 to cnt

void jack_ringbuffer_write_advance | ( | jack_ringbuffer_t * | rb,
|  | size_t | cnt |
| ) |  |  |

Advance the write pointer.

After data have been written the ringbuffer using the pointers returned by jack_ringbuffer_get_write_vector(), use this function to advance the buffer pointer, making the data available for future read operations.

Parameters:

  | rb | a pointer to the ringbuffer structure.
  | cnt | the number of bytes written.

size_t jack_ringbuffer_write_space | ( | const jack_ringbuffer_t * | rb | ) |

Return the number of bytes available for writing.

Parameters:

  | rb | a pointer to the ringbuffer structure.

Returns:
  the amount of free space (in bytes) available for writing.