Commit c2a484cd authored by sletz's avatar sletz
Browse files

Synchronize jack2 public headers with jack1 ones.

git-svn-id: http://subversion.jackaudio.org/jack/jack2/trunk/jackmp@3231 0c269be4-1314-0410-8aa9-9f06e86f4224
parent 3a526089
......@@ -23,6 +23,10 @@ Michael Voigt
Jackdmp changes log
---------------------------
2009-01-05 Stephane Letz <letz@grame.fr>
* Synchronize jack2 public headers with jack1 ones.
2008-12-18 Stephane Letz <letz@grame.fr>
* For ALSA driver, synchronize with latest jack1 memops functions.
......
......@@ -25,11 +25,12 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
namespace Jack
{
namespace detail
{
/*!
\brief An inter process synchronization primitive.
*/
namespace detail
{
class JackSynchro
{
......
......@@ -50,13 +50,13 @@ class JackRunnableInterface
virtual bool Execute() = 0; /*! Must be implemented by subclasses */
};
namespace detail
{
/*!
\brief The thread base class.
*/
namespace detail
{
class SERVER_EXPORT JackThreadInterface
{
......
......@@ -78,6 +78,11 @@ extern "C" {
} /* Adjust editor indent */
#endif
/**
* @defgroup ServerControl Controling the server
* @{
*/
/**
* Call this function to setup process signal handling. As a general
* rule, it is required for proper operation for the server object.
......@@ -320,7 +325,7 @@ jackctl_parameter_get_default_value(
*/
bool
jackctl_parameter_has_range_constraint(
jackctl_parameter_t * parameter_ptr);
jackctl_parameter_t * parameter);
/**
* Call this function check whether parameter has enumeration constraint.
......@@ -331,7 +336,7 @@ jackctl_parameter_has_range_constraint(
*/
bool
jackctl_parameter_has_enum_constraint(
jackctl_parameter_t * parameter_ptr);
jackctl_parameter_t * parameter);
/**
* Call this function get how many enumeration values parameter has.
......@@ -342,7 +347,7 @@ jackctl_parameter_has_enum_constraint(
*/
uint32_t
jackctl_parameter_get_enum_constraints_count(
jackctl_parameter_t * parameter_ptr);
jackctl_parameter_t * parameter);
/**
* Call this function to get parameter enumeration value.
......@@ -354,7 +359,7 @@ jackctl_parameter_get_enum_constraints_count(
*/
union jackctl_parameter_value
jackctl_parameter_get_enum_constraint_value(
jackctl_parameter_t * parameter_ptr,
jackctl_parameter_t * parameter,
uint32_t index);
/**
......@@ -367,7 +372,7 @@ jackctl_parameter_get_enum_constraint_value(
*/
const char *
jackctl_parameter_get_enum_constraint_description(
jackctl_parameter_t * parameter_ptr,
jackctl_parameter_t * parameter,
uint32_t index);
/**
......@@ -379,7 +384,7 @@ jackctl_parameter_get_enum_constraint_description(
*/
void
jackctl_parameter_get_range_constraint(
jackctl_parameter_t * parameter_ptr,
jackctl_parameter_t * parameter,
union jackctl_parameter_value * min_ptr,
union jackctl_parameter_value * max_ptr);
......@@ -393,7 +398,7 @@ jackctl_parameter_get_range_constraint(
*/
bool
jackctl_parameter_constraint_is_strict(
jackctl_parameter_t * parameter_ptr);
jackctl_parameter_t * parameter);
/**
* Call this function to check whether parameter has fake values,
......@@ -406,7 +411,7 @@ jackctl_parameter_constraint_is_strict(
*/
bool
jackctl_parameter_constraint_is_fake_value(
jackctl_parameter_t * parameter_ptr);
jackctl_parameter_t * parameter);
/**
* Call this function to get list of available internal clients. List node data
......@@ -503,6 +508,8 @@ jack_log(
const char *format,
...);
/* @} */
#if 0
{ /* Adjust editor indent */
#endif
......
......@@ -27,101 +27,101 @@ extern "C"
#include <jack/types.h>
/**
* Get an internal client's name. This is useful when @ref
* JackUseExactName was not specified on jack_internal_client_load()
* and @ref JackNameNotUnique status was returned. In that case, the
* actual name will differ from the @a client_name requested.
*
* @param client requesting JACK client's handle.
*
* @param intclient handle returned from jack_internal_client_load()
* or jack_internal_client_handle().
*
* @return NULL if unsuccessful, otherwise pointer to the internal
* client name obtained from the heap via malloc(). The caller should
* free() this storage when no longer needed.
*/
char *jack_get_internal_client_name (jack_client_t *client,
jack_intclient_t intclient);
/**
* Get an internal client's name. This is useful when @ref
* JackUseExactName was not specified on jack_internal_client_load()
* and @ref JackNameNotUnique status was returned. In that case, the
* actual name will differ from the @a client_name requested.
*
* @param client requesting JACK client's handle.
*
* @param intclient handle returned from jack_internal_client_load()
* or jack_internal_client_handle().
*
* @return NULL if unsuccessful, otherwise pointer to the internal
* client name obtained from the heap via malloc(). The caller should
* free() this storage when no longer needed.
*/
char *jack_get_internal_client_name (jack_client_t *client,
jack_intclient_t intclient);
/**
* Return the @ref jack_intclient_t handle for an internal client
* running in the JACK server.
*
* @param client requesting JACK client's handle.
*
* @param client_name for the internal client of no more than
* jack_client_name_size() characters. The name scope is local to the
* current server.
*
* @param status (if non-NULL) an address for JACK to return
* information from this operation. This status word is formed by
* OR-ing together the relevant @ref JackStatus bits.
*
* @return Opaque internal client handle if successful. If 0, the
* internal client was not found, and @a *status includes the @ref
* JackNoSuchClient and @ref JackFailure bits.
*/
jack_intclient_t jack_internal_client_handle (jack_client_t *client,
const char *client_name,
jack_status_t *status);
/**
* Return the @ref jack_intclient_t handle for an internal client
* running in the JACK server.
*
* @param client requesting JACK client's handle.
*
* @param client_name for the internal client of no more than
* jack_client_name_size() characters. The name scope is local to the
* current server.
*
* @param status (if non-NULL) an address for JACK to return
* information from this operation. This status word is formed by
* OR-ing together the relevant @ref JackStatus bits.
*
* @return Opaque internal client handle if successful. If 0, the
* internal client was not found, and @a *status includes the @ref
* JackNoSuchClient and @ref JackFailure bits.
*/
jack_intclient_t jack_internal_client_handle (jack_client_t *client,
const char *client_name,
jack_status_t *status);
/**
* Load an internal client into the JACK server.
*
* Internal clients run inside the JACK server process. They can use
* most of the same functions as external clients. Each internal
* client is built as a shared object module, which must declare
* jack_initialize() and jack_finish() entry points called at load and
* unload times. See @ref inprocess.c for an example.
*
* @param client loading JACK client's handle.
*
* @param client_name of at most jack_client_name_size() characters
* for the internal client to load. The name scope is local to the
* current server.
*
* @param options formed by OR-ing together @ref JackOptions bits.
* Only the @ref JackLoadOptions bits are valid.
*
* @param status (if non-NULL) an address for JACK to return
* information from the load operation. This status word is formed by
* OR-ing together the relevant @ref JackStatus bits.
*
* <b>Optional parameters:</b> depending on corresponding [@a options
* bits] additional parameters may follow @a status (in this order).
*
* @arg [@ref JackLoadName] <em>(char *) load_name</em> is the shared
* object file from which to load the new internal client (otherwise
* use the @a client_name).
*
* @arg [@ref JackLoadInit] <em>(char *) load_init</em> an arbitary
* string passed to the internal client's jack_initialize() routine
* (otherwise NULL), of no more than @ref JACK_LOAD_INIT_LIMIT bytes.
*
* @return Opaque internal client handle if successful. If this is 0,
* the load operation failed, the internal client was not loaded, and
* @a *status includes the @ref JackFailure bit.
*/
jack_intclient_t jack_internal_client_load (jack_client_t *client,
const char *client_name,
jack_options_t options,
jack_status_t *status, ...);
/**
* Unload an internal client from a JACK server. This calls the
* intclient's jack_finish() entry point then removes it. See @ref
* inprocess.c for an example.
*
* @param client unloading JACK client's handle.
*
* @param intclient handle returned from jack_internal_client_load() or
* jack_internal_client_handle().
*
* @return 0 if successful, otherwise @ref JackStatus bits.
*/
jack_status_t jack_internal_client_unload (jack_client_t *client,
jack_intclient_t intclient);
/**
* Load an internal client into the JACK server.
*
* Internal clients run inside the JACK server process. They can use
* most of the same functions as external clients. Each internal
* client is built as a shared object module, which must declare
* jack_initialize() and jack_finish() entry points called at load and
* unload times. See @ref inprocess.c for an example.
*
* @param client loading JACK client's handle.
*
* @param client_name of at most jack_client_name_size() characters
* for the internal client to load. The name scope is local to the
* current server.
*
* @param options formed by OR-ing together @ref JackOptions bits.
* Only the @ref JackLoadOptions bits are valid.
*
* @param status (if non-NULL) an address for JACK to return
* information from the load operation. This status word is formed by
* OR-ing together the relevant @ref JackStatus bits.
*
* <b>Optional parameters:</b> depending on corresponding [@a options
* bits] additional parameters may follow @a status (in this order).
*
* @arg [@ref JackLoadName] <em>(char *) load_name</em> is the shared
* object file from which to load the new internal client (otherwise
* use the @a client_name).
*
* @arg [@ref JackLoadInit] <em>(char *) load_init</em> an arbitary
* string passed to the internal client's jack_initialize() routine
* (otherwise NULL), of no more than @ref JACK_LOAD_INIT_LIMIT bytes.
*
* @return Opaque internal client handle if successful. If this is 0,
* the load operation failed, the internal client was not loaded, and
* @a *status includes the @ref JackFailure bit.
*/
jack_intclient_t jack_internal_client_load (jack_client_t *client,
const char *client_name,
jack_options_t options,
jack_status_t *status, ...);
/**
* Unload an internal client from a JACK server. This calls the
* intclient's jack_finish() entry point then removes it. See @ref
* inprocess.c for an example.
*
* @param client unloading JACK client's handle.
*
* @param intclient handle returned from jack_internal_client_load() or
* jack_internal_client_handle().
*
* @return 0 if successful, otherwise @ref JackStatus bits.
*/
jack_status_t jack_internal_client_unload (jack_client_t *client,
jack_intclient_t intclient);
#ifdef __cplusplus
}
......
This diff is collapsed.
......@@ -42,6 +42,11 @@ typedef struct _jack_midi_event
} jack_midi_event_t;
/**
* @defgroup MIDIAPI Reading and writing MIDI data
* @{
*/
/* Get number of events in a port buffer.
*
* @param port_buffer Port buffer from which to retrieve event.
......@@ -142,6 +147,7 @@ jack_midi_event_write(void *port_buffer,
jack_nframes_t
jack_midi_get_lost_event_count(void *port_buffer);
/*@}*/
#ifdef __cplusplus
}
......
......@@ -28,203 +28,203 @@ extern "C"
#include <sys/types.h>
/** @file ringbuffer.h
*
* 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.
*/
typedef struct {
char *buf;
size_t len;
}
jack_ringbuffer_data_t ;
typedef struct {
char *buf;
volatile size_t write_ptr;
volatile size_t read_ptr;
size_t size;
size_t size_mask;
int mlocked;
}
jack_ringbuffer_t ;
/**
* 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.
*
* @param sz the ringbuffer size in bytes.
*
* @return a pointer to a new jack_ringbuffer_t, if successful; NULL
* otherwise.
*/
jack_ringbuffer_t *jack_ringbuffer_create(size_t sz);
/**
* Frees the ringbuffer data structure allocated by an earlier call to
* jack_ringbuffer_create().
*
* @param rb a pointer to the ringbuffer structure.
*/
void jack_ringbuffer_free(jack_ringbuffer_t *rb);
/**
* 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 @a len field, which
* may be zero or greater. If the @a len field is non-zero, then data
* can be read in a contiguous fashion using the address given in the
* corresponding @a buf field.
*
* If the second element has a non-zero @a len field, then a second
* contiguous stretch of data can be read from the address given in
* its corresponding @a buf field.
*
* @param rb a pointer to the ringbuffer structure.
* @param vec a pointer to a 2 element array of jack_ringbuffer_data_t.
*
*/
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 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 @a len field, which
* may be zero or greater. If the @a len field is non-zero, then data
* can be written in a contiguous fashion using the address given in
* the corresponding @a buf field.
*
* If the second element has a non-zero @a len field, then a second
* contiguous stretch of data can be written to the address given in
* the corresponding @a buf field.
*
* @param rb a pointer to the ringbuffer structure.
* @param 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);
/**
* Read data from the ringbuffer.
*
* @param rb a pointer to the ringbuffer structure.
* @param dest a pointer to a buffer where data read from the
* ringbuffer will go.
* @param cnt the number of bytes to read.
*
* @return 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. 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().
*
* @param rb a pointer to the ringbuffer structure.
* @param dest a pointer to a buffer where data read from the
* ringbuffer will go.
* @param cnt the number of bytes to read.
*
* @return the number of bytes read, which may range from 0 to cnt.
*/
size_t jack_ringbuffer_peek(jack_ringbuffer_t *rb, char *dest, 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.
*
* @param rb a pointer to the ringbuffer structure.
* @param cnt the number of bytes read.
*/
void jack_ringbuffer_read_advance(jack_ringbuffer_t *rb, size_t cnt);
/**
* Return the number of bytes available for reading.
*
* @param rb a pointer to the ringbuffer structure.
*
* @return the number of bytes available to read.
*/
size_t jack_ringbuffer_read_space(const jack_ringbuffer_t *rb);
/**
* Lock a ringbuffer data block into memory.
*
* Uses the mlock() system call. This is not a realtime operation.
*
* @param rb a pointer to the ringbuffer structure.
*/
int jack_ringbuffer_mlock(jack_ringbuffer_t *rb);
/**
* Reset the read and write pointers, making an empty buffer.
*
* This is not thread safe.
*
* @param rb a pointer to the ringbuffer structure.
*/
void jack_ringbuffer_reset(jack_ringbuffer_t *rb);
/**
* Write data into the ringbuffer.
*
* @param rb a pointer to the ringbuffer structure.
* @param src a pointer to the data to be written to the ringbuffer.
* @param cnt the number of bytes to write.
*
* @return the number of bytes write, which may range from 0 to cnt
*/
size_t jack_ringbuffer_write(jack_ringbuffer_t *rb, const char *src,
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.
*
* @param rb a pointer to the ringbuffer structure.
* @param cnt the number of bytes written.
*/
void jack_ringbuffer_write_advance(jack_ringbuffer_t *rb, size_t cnt);
/**
* Return the number of bytes available for writing.
*
* @param rb a pointer to the ringbuffer structure.
*
* @return the amount of free space (in bytes) available for writing.
*/
size_t jack_ringbuffer_write_space(const jack_ringbuffer_t *rb);
/** @file ringbuffer.h
*
* 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.
*/
typedef struct {
char *buf;
size_t len;
}
jack_ringbuffer_data_t ;
typedef struct {
char *buf;
volatile size_t write_ptr;
volatile size_t read_ptr;
size_t size;
size_t size_mask;
int mlocked;
}
jack_ringbuffer_t ;
/**
* 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.
*
* @param sz the ringbuffer size in bytes.
*
* @return a pointer to a new jack_ringbuffer_t, if successful; NULL
* otherwise.
*/
jack_ringbuffer_t *jack_ringbuffer_create(size_t sz);
/**
* Frees the ringbuffer data structure allocated by an earlier call to
* jack_ringbuffer_create().
*
* @param rb a pointer to the ringbuffer structure.
*/
void jack_ringbuffer_free(jack_ringbuffer_t *rb);
/**
* 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 @a len field, which
* may be zero or greater. If the @a len field is non-zero, then data
* can be read in a contiguous fashion using the address given in the
* corresponding @a buf field.
*
* If the second element has a non-zero @a len field, then a second
* contiguous stretch of data can be read from the address given in
* its corresponding @a buf field.
*
* @param rb a pointer to the ringbuffer structure.
* @param vec a pointer to a 2 element array of jack_ringbuffer_data_t.
*
*/
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 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 @a len field, which
* may be zero or greater. If the @a len field is non-zero, then data