JACK-AUDIO-CONNECTION-KIT
Data Structures | Functions
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_tjack_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_create()

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
szthe ringbuffer size in bytes.
Returns
a pointer to a new jack_ringbuffer_t, if successful; NULL otherwise.

◆ jack_ringbuffer_free()

void jack_ringbuffer_free ( jack_ringbuffer_t rb)

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

Parameters
rba pointer to the ringbuffer structure.

◆ jack_ringbuffer_get_read_vector()

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
rba pointer to the ringbuffer structure.
veca pointer to a 2 element array of jack_ringbuffer_data_t.

◆ jack_ringbuffer_get_write_vector()

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
rba pointer to the ringbuffer structure.
veca pointer to a 2 element array of jack_ringbuffer_data_t.

◆ jack_ringbuffer_mlock()

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
rba pointer to the ringbuffer structure.

◆ jack_ringbuffer_peek()

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
rba pointer to the ringbuffer structure.
desta pointer to a buffer where data read from the ringbuffer will go.
cntthe number of bytes to read.
Returns
the number of bytes read, which may range from 0 to cnt.

◆ jack_ringbuffer_read()

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

Read data from the ringbuffer.

Parameters
rba pointer to the ringbuffer structure.
desta pointer to a buffer where data read from the ringbuffer will go.
cntthe number of bytes to read.
Returns
the number of bytes read, which may range from 0 to cnt.

◆ jack_ringbuffer_read_advance()

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
rba pointer to the ringbuffer structure.
cntthe number of bytes read.

◆ jack_ringbuffer_read_space()

size_t jack_ringbuffer_read_space ( const jack_ringbuffer_t rb)

Return the number of bytes available for reading.

Parameters
rba pointer to the ringbuffer structure.
Returns
the number of bytes available to read.

◆ jack_ringbuffer_reset()

void jack_ringbuffer_reset ( jack_ringbuffer_t rb)

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

This is not thread safe.

Parameters
rba pointer to the ringbuffer structure.

◆ jack_ringbuffer_write()

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

Write data into the ringbuffer.

Parameters
rba pointer to the ringbuffer structure.
srca pointer to the data to be written to the ringbuffer.
cntthe number of bytes to write.
Returns
the number of bytes write, which may range from 0 to cnt

◆ jack_ringbuffer_write_advance()

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
rba pointer to the ringbuffer structure.
cntthe number of bytes written.

◆ jack_ringbuffer_write_space()

size_t jack_ringbuffer_write_space ( const jack_ringbuffer_t rb)

Return the number of bytes available for writing.

Parameters
rba pointer to the ringbuffer structure.
Returns
the amount of free space (in bytes) available for writing.