\hypertarget{ringbuffer_8h}{
\section{ringbuffer.h File Reference}
\label{ringbuffer_8h}\index{ringbuffer.h@{ringbuffer.h}}
}
{\tt \#include $<$sys/types.h$>$}\par
\subsection*{Data Structures}
\begin{CompactItemize}
\item 
struct \hyperlink{structjack__ringbuffer__data__t}{jack\_\-ringbuffer\_\-data\_\-t}
\item 
struct \hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t}
\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$ \hyperlink{ringbuffer_8h_94b9e37d52ba9f709708642ef828d8db}{jack\_\-ringbuffer\_\-create} (size\_\-t sz)
\item 
void \hyperlink{ringbuffer_8h_8fb42ae0f48d8b577f2646d76916efa2}{jack\_\-ringbuffer\_\-free} (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$rb)
\item 
void \hyperlink{ringbuffer_8h_9b8b13016211aac96cbe641fc7be36b7}{jack\_\-ringbuffer\_\-get\_\-read\_\-vector} (const \hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$rb, \hyperlink{structjack__ringbuffer__data__t}{jack\_\-ringbuffer\_\-data\_\-t} $\ast$vec)
\item 
void \hyperlink{ringbuffer_8h_4be44774c7f46e039b2bc4bac60cf210}{jack\_\-ringbuffer\_\-get\_\-write\_\-vector} (const \hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$rb, \hyperlink{structjack__ringbuffer__data__t}{jack\_\-ringbuffer\_\-data\_\-t} $\ast$vec)
\item 
size\_\-t \hyperlink{ringbuffer_8h_73860122ca415c87dade24feeb7d0873}{jack\_\-ringbuffer\_\-read} (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$rb, char $\ast$dest, size\_\-t cnt)
\item 
size\_\-t \hyperlink{ringbuffer_8h_3368ff9f5a01051cb80efea7b77f8f23}{jack\_\-ringbuffer\_\-peek} (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$rb, char $\ast$dest, size\_\-t cnt)
\item 
void \hyperlink{ringbuffer_8h_d2c7ab71ad01f7823ac210e671c7f049}{jack\_\-ringbuffer\_\-read\_\-advance} (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$rb, size\_\-t cnt)
\item 
size\_\-t \hyperlink{ringbuffer_8h_2c3d28b148948aa5d0cd1096824bd056}{jack\_\-ringbuffer\_\-read\_\-space} (const \hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$rb)
\item 
int \hyperlink{ringbuffer_8h_ce4504a64f544c73b6aece27190249f2}{jack\_\-ringbuffer\_\-mlock} (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$rb)
\item 
void \hyperlink{ringbuffer_8h_da057fefeedbe71a28e8faf5d3f9a326}{jack\_\-ringbuffer\_\-reset} (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$rb)
\item 
size\_\-t \hyperlink{ringbuffer_8h_d1fdaca64cb6b043be013426c237c312}{jack\_\-ringbuffer\_\-write} (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$rb, const char $\ast$src, size\_\-t cnt)
\item 
void \hyperlink{ringbuffer_8h_9e1d3d507aa484370f406d00a4faf001}{jack\_\-ringbuffer\_\-write\_\-advance} (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$rb, size\_\-t cnt)
\item 
size\_\-t \hyperlink{ringbuffer_8h_f61c5dd39e72df8de2d006dc9f9ddfc2}{jack\_\-ringbuffer\_\-write\_\-space} (const \hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$rb)
\end{CompactItemize}


\subsection{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. 

\subsection{Function Documentation}
\hypertarget{ringbuffer_8h_94b9e37d52ba9f709708642ef828d8db}{
\index{ringbuffer.h@{ringbuffer.h}!jack_ringbuffer_create@{jack\_\-ringbuffer\_\-create}}
\index{jack_ringbuffer_create@{jack\_\-ringbuffer\_\-create}!ringbuffer.h@{ringbuffer.h}}
\subsubsection[jack\_\-ringbuffer\_\-create]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t}$\ast$ jack\_\-ringbuffer\_\-create (size\_\-t {\em sz})}}
\label{ringbuffer_8h_94b9e37d52ba9f709708642ef828d8db}


Allocates a ringbuffer data structure of a specified size. The caller must arrange for a call to \hyperlink{ringbuffer_8h_8fb42ae0f48d8b577f2646d76916efa2}{jack\_\-ringbuffer\_\-free()} to release the memory associated with the ringbuffer.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em sz}]the ringbuffer size in bytes.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]a pointer to a new \hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t}, if successful; NULL otherwise. \end{Desc}
\hypertarget{ringbuffer_8h_8fb42ae0f48d8b577f2646d76916efa2}{
\index{ringbuffer.h@{ringbuffer.h}!jack_ringbuffer_free@{jack\_\-ringbuffer\_\-free}}
\index{jack_ringbuffer_free@{jack\_\-ringbuffer\_\-free}!ringbuffer.h@{ringbuffer.h}}
\subsubsection[jack\_\-ringbuffer\_\-free]{\setlength{\rightskip}{0pt plus 5cm}void jack\_\-ringbuffer\_\-free (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$ {\em rb})}}
\label{ringbuffer_8h_8fb42ae0f48d8b577f2646d76916efa2}


Frees the ringbuffer data structure allocated by an earlier call to \hyperlink{ringbuffer_8h_94b9e37d52ba9f709708642ef828d8db}{jack\_\-ringbuffer\_\-create()}.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rb}]a pointer to the ringbuffer structure. \end{description}
\end{Desc}
\hypertarget{ringbuffer_8h_9b8b13016211aac96cbe641fc7be36b7}{
\index{ringbuffer.h@{ringbuffer.h}!jack_ringbuffer_get_read_vector@{jack\_\-ringbuffer\_\-get\_\-read\_\-vector}}
\index{jack_ringbuffer_get_read_vector@{jack\_\-ringbuffer\_\-get\_\-read\_\-vector}!ringbuffer.h@{ringbuffer.h}}
\subsubsection[jack\_\-ringbuffer\_\-get\_\-read\_\-vector]{\setlength{\rightskip}{0pt plus 5cm}void jack\_\-ringbuffer\_\-get\_\-read\_\-vector (const \hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$ {\em rb}, \hyperlink{structjack__ringbuffer__data__t}{jack\_\-ringbuffer\_\-data\_\-t} $\ast$ {\em vec})}}
\label{ringbuffer_8h_9b8b13016211aac96cbe641fc7be36b7}


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 \hyperlink{structjack__ringbuffer__data__t}{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 {\em len\/} field, which may be zero or greater. If the {\em len\/} field is non-zero, then data can be read in a contiguous fashion using the address given in the corresponding {\em buf\/} field.

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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rb}]a pointer to the ringbuffer structure. \item[{\em vec}]a pointer to a 2 element array of \hyperlink{structjack__ringbuffer__data__t}{jack\_\-ringbuffer\_\-data\_\-t}. \end{description}
\end{Desc}
\hypertarget{ringbuffer_8h_4be44774c7f46e039b2bc4bac60cf210}{
\index{ringbuffer.h@{ringbuffer.h}!jack_ringbuffer_get_write_vector@{jack\_\-ringbuffer\_\-get\_\-write\_\-vector}}
\index{jack_ringbuffer_get_write_vector@{jack\_\-ringbuffer\_\-get\_\-write\_\-vector}!ringbuffer.h@{ringbuffer.h}}
\subsubsection[jack\_\-ringbuffer\_\-get\_\-write\_\-vector]{\setlength{\rightskip}{0pt plus 5cm}void jack\_\-ringbuffer\_\-get\_\-write\_\-vector (const \hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$ {\em rb}, \hyperlink{structjack__ringbuffer__data__t}{jack\_\-ringbuffer\_\-data\_\-t} $\ast$ {\em vec})}}
\label{ringbuffer_8h_4be44774c7f46e039b2bc4bac60cf210}


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 \hyperlink{structjack__ringbuffer__data__t}{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 {\em len\/} field, which may be zero or greater. If the {\em len\/} field is non-zero, then data can be written in a contiguous fashion using the address given in the corresponding {\em buf\/} field.

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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rb}]a pointer to the ringbuffer structure. \item[{\em vec}]a pointer to a 2 element array of \hyperlink{structjack__ringbuffer__data__t}{jack\_\-ringbuffer\_\-data\_\-t}. \end{description}
\end{Desc}
\hypertarget{ringbuffer_8h_ce4504a64f544c73b6aece27190249f2}{
\index{ringbuffer.h@{ringbuffer.h}!jack_ringbuffer_mlock@{jack\_\-ringbuffer\_\-mlock}}
\index{jack_ringbuffer_mlock@{jack\_\-ringbuffer\_\-mlock}!ringbuffer.h@{ringbuffer.h}}
\subsubsection[jack\_\-ringbuffer\_\-mlock]{\setlength{\rightskip}{0pt plus 5cm}int jack\_\-ringbuffer\_\-mlock (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$ {\em rb})}}
\label{ringbuffer_8h_ce4504a64f544c73b6aece27190249f2}


Lock a ringbuffer data block into memory.

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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rb}]a pointer to the ringbuffer structure. \end{description}
\end{Desc}
\hypertarget{ringbuffer_8h_3368ff9f5a01051cb80efea7b77f8f23}{
\index{ringbuffer.h@{ringbuffer.h}!jack_ringbuffer_peek@{jack\_\-ringbuffer\_\-peek}}
\index{jack_ringbuffer_peek@{jack\_\-ringbuffer\_\-peek}!ringbuffer.h@{ringbuffer.h}}
\subsubsection[jack\_\-ringbuffer\_\-peek]{\setlength{\rightskip}{0pt plus 5cm}size\_\-t jack\_\-ringbuffer\_\-peek (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$ {\em rb}, char $\ast$ {\em dest}, size\_\-t {\em cnt})}}
\label{ringbuffer_8h_3368ff9f5a01051cb80efea7b77f8f23}


Read data from the ringbuffer. Opposed to \hyperlink{ringbuffer_8h_73860122ca415c87dade24feeb7d0873}{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 \char`\"{}raw\char`\"{} non-copy inspection of the data in the ringbuffer use \hyperlink{ringbuffer_8h_9b8b13016211aac96cbe641fc7be36b7}{jack\_\-ringbuffer\_\-get\_\-read\_\-vector()}.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rb}]a pointer to the ringbuffer structure. \item[{\em dest}]a pointer to a buffer where data read from the ringbuffer will go. \item[{\em cnt}]the number of bytes to read.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the number of bytes read, which may range from 0 to cnt. \end{Desc}
\hypertarget{ringbuffer_8h_73860122ca415c87dade24feeb7d0873}{
\index{ringbuffer.h@{ringbuffer.h}!jack_ringbuffer_read@{jack\_\-ringbuffer\_\-read}}
\index{jack_ringbuffer_read@{jack\_\-ringbuffer\_\-read}!ringbuffer.h@{ringbuffer.h}}
\subsubsection[jack\_\-ringbuffer\_\-read]{\setlength{\rightskip}{0pt plus 5cm}size\_\-t jack\_\-ringbuffer\_\-read (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$ {\em rb}, char $\ast$ {\em dest}, size\_\-t {\em cnt})}}
\label{ringbuffer_8h_73860122ca415c87dade24feeb7d0873}


Read data from the ringbuffer.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rb}]a pointer to the ringbuffer structure. \item[{\em dest}]a pointer to a buffer where data read from the ringbuffer will go. \item[{\em cnt}]the number of bytes to read.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the number of bytes read, which may range from 0 to cnt. \end{Desc}
\hypertarget{ringbuffer_8h_d2c7ab71ad01f7823ac210e671c7f049}{
\index{ringbuffer.h@{ringbuffer.h}!jack_ringbuffer_read_advance@{jack\_\-ringbuffer\_\-read\_\-advance}}
\index{jack_ringbuffer_read_advance@{jack\_\-ringbuffer\_\-read\_\-advance}!ringbuffer.h@{ringbuffer.h}}
\subsubsection[jack\_\-ringbuffer\_\-read\_\-advance]{\setlength{\rightskip}{0pt plus 5cm}void jack\_\-ringbuffer\_\-read\_\-advance (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$ {\em rb}, size\_\-t {\em cnt})}}
\label{ringbuffer_8h_d2c7ab71ad01f7823ac210e671c7f049}


Advance the read pointer.

After data have been read from the ringbuffer using the pointers returned by \hyperlink{ringbuffer_8h_9b8b13016211aac96cbe641fc7be36b7}{jack\_\-ringbuffer\_\-get\_\-read\_\-vector()}, use this function to advance the buffer pointers, making that space available for future write operations.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rb}]a pointer to the ringbuffer structure. \item[{\em cnt}]the number of bytes read. \end{description}
\end{Desc}
\hypertarget{ringbuffer_8h_2c3d28b148948aa5d0cd1096824bd056}{
\index{ringbuffer.h@{ringbuffer.h}!jack_ringbuffer_read_space@{jack\_\-ringbuffer\_\-read\_\-space}}
\index{jack_ringbuffer_read_space@{jack\_\-ringbuffer\_\-read\_\-space}!ringbuffer.h@{ringbuffer.h}}
\subsubsection[jack\_\-ringbuffer\_\-read\_\-space]{\setlength{\rightskip}{0pt plus 5cm}size\_\-t jack\_\-ringbuffer\_\-read\_\-space (const \hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$ {\em rb})}}
\label{ringbuffer_8h_2c3d28b148948aa5d0cd1096824bd056}


Return the number of bytes available for reading.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rb}]a pointer to the ringbuffer structure.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the number of bytes available to read. \end{Desc}
\hypertarget{ringbuffer_8h_da057fefeedbe71a28e8faf5d3f9a326}{
\index{ringbuffer.h@{ringbuffer.h}!jack_ringbuffer_reset@{jack\_\-ringbuffer\_\-reset}}
\index{jack_ringbuffer_reset@{jack\_\-ringbuffer\_\-reset}!ringbuffer.h@{ringbuffer.h}}
\subsubsection[jack\_\-ringbuffer\_\-reset]{\setlength{\rightskip}{0pt plus 5cm}void jack\_\-ringbuffer\_\-reset (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$ {\em rb})}}
\label{ringbuffer_8h_da057fefeedbe71a28e8faf5d3f9a326}


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

This is not thread safe.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rb}]a pointer to the ringbuffer structure. \end{description}
\end{Desc}
\hypertarget{ringbuffer_8h_d1fdaca64cb6b043be013426c237c312}{
\index{ringbuffer.h@{ringbuffer.h}!jack_ringbuffer_write@{jack\_\-ringbuffer\_\-write}}
\index{jack_ringbuffer_write@{jack\_\-ringbuffer\_\-write}!ringbuffer.h@{ringbuffer.h}}
\subsubsection[jack\_\-ringbuffer\_\-write]{\setlength{\rightskip}{0pt plus 5cm}size\_\-t jack\_\-ringbuffer\_\-write (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$ {\em rb}, const char $\ast$ {\em src}, size\_\-t {\em cnt})}}
\label{ringbuffer_8h_d1fdaca64cb6b043be013426c237c312}


Write data into the ringbuffer.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rb}]a pointer to the ringbuffer structure. \item[{\em src}]a pointer to the data to be written to the ringbuffer. \item[{\em cnt}]the number of bytes to write.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the number of bytes write, which may range from 0 to cnt \end{Desc}
\hypertarget{ringbuffer_8h_9e1d3d507aa484370f406d00a4faf001}{
\index{ringbuffer.h@{ringbuffer.h}!jack_ringbuffer_write_advance@{jack\_\-ringbuffer\_\-write\_\-advance}}
\index{jack_ringbuffer_write_advance@{jack\_\-ringbuffer\_\-write\_\-advance}!ringbuffer.h@{ringbuffer.h}}
\subsubsection[jack\_\-ringbuffer\_\-write\_\-advance]{\setlength{\rightskip}{0pt plus 5cm}void jack\_\-ringbuffer\_\-write\_\-advance (\hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$ {\em rb}, size\_\-t {\em cnt})}}
\label{ringbuffer_8h_9e1d3d507aa484370f406d00a4faf001}


Advance the write pointer.

After data have been written the ringbuffer using the pointers returned by \hyperlink{ringbuffer_8h_4be44774c7f46e039b2bc4bac60cf210}{jack\_\-ringbuffer\_\-get\_\-write\_\-vector()}, use this function to advance the buffer pointer, making the data available for future read operations.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rb}]a pointer to the ringbuffer structure. \item[{\em cnt}]the number of bytes written. \end{description}
\end{Desc}
\hypertarget{ringbuffer_8h_f61c5dd39e72df8de2d006dc9f9ddfc2}{
\index{ringbuffer.h@{ringbuffer.h}!jack_ringbuffer_write_space@{jack\_\-ringbuffer\_\-write\_\-space}}
\index{jack_ringbuffer_write_space@{jack\_\-ringbuffer\_\-write\_\-space}!ringbuffer.h@{ringbuffer.h}}
\subsubsection[jack\_\-ringbuffer\_\-write\_\-space]{\setlength{\rightskip}{0pt plus 5cm}size\_\-t jack\_\-ringbuffer\_\-write\_\-space (const \hyperlink{structjack__ringbuffer__t}{jack\_\-ringbuffer\_\-t} $\ast$ {\em rb})}}
\label{ringbuffer_8h_f61c5dd39e72df8de2d006dc9f9ddfc2}


Return the number of bytes available for writing.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rb}]a pointer to the ringbuffer structure.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the amount of free space (in bytes) available for writing. \end{Desc}
