diff --git a/ChangeLog b/ChangeLog index 5cbf23f1..73825414 100644 --- a/ChangeLog +++ b/ChangeLog @@ -23,6 +23,10 @@ Michael Voigt Jackdmp changes log --------------------------- +2009-01-05 Stephane Letz + + * Synchronize jack2 public headers with jack1 ones. + 2008-12-18 Stephane Letz * For ALSA driver, synchronize with latest jack1 memops functions. diff --git a/common/JackSynchro.h b/common/JackSynchro.h index 34bcb5fd..05180018 100644 --- a/common/JackSynchro.h +++ b/common/JackSynchro.h @@ -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 { diff --git a/common/JackThread.h b/common/JackThread.h index 5f3d81f5..56c62419 100644 --- a/common/JackThread.h +++ b/common/JackThread.h @@ -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 { diff --git a/common/jack/control.h b/common/jack/control.h index 63f061ac..17436f07 100644 --- a/common/jack/control.h +++ b/common/jack/control.h @@ -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 diff --git a/common/jack/intclient.h b/common/jack/intclient.h index 249e62f4..50d758d9 100644 --- a/common/jack/intclient.h +++ b/common/jack/intclient.h @@ -27,101 +27,101 @@ extern "C" #include - /** - * 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. - * - * Optional parameters: depending on corresponding [@a options - * bits] additional parameters may follow @a status (in this order). - * - * @arg [@ref JackLoadName] (char *) load_name is the shared - * object file from which to load the new internal client (otherwise - * use the @a client_name). - * - * @arg [@ref JackLoadInit] (char *) load_init 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. + * + * Optional parameters: depending on corresponding [@a options + * bits] additional parameters may follow @a status (in this order). + * + * @arg [@ref JackLoadName] (char *) load_name is the shared + * object file from which to load the new internal client (otherwise + * use the @a client_name). + * + * @arg [@ref JackLoadInit] (char *) load_init 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 } diff --git a/common/jack/jack.h b/common/jack/jack.h index fdebe78a..a0b0e397 100644 --- a/common/jack/jack.h +++ b/common/jack/jack.h @@ -30,998 +30,1045 @@ extern "C" #include #include +/** + * Note: More documentation can be found in jack/types.h. + */ + +/** +* @defgroup ClientFunctions Creating & manipulating clients +* @{ +*/ + +/** + * Call this function to get version of the JACK, in form of several numbers + * + * @param major_ptr pointer to variable receiving major version of JACK. + * + * @param minor_ptr pointer to variable receiving minor version of JACK. + * + * @param major_ptr pointer to variable receiving micro version of JACK. + * + * @param major_ptr pointer to variable receiving protocol version of JACK. + * + */ +void +jack_get_version( + int *major_ptr, + int *minor_ptr, + int *micro_ptr, + int *proto_ptr); + +/** + * Call this function to get version of the JACK, in form of a string + * + * @return Human readable string describing JACK version being used. + * + */ +const char * +jack_get_version_string(); + +/** + * Open an external client session with a JACK server. This interface + * is more complex but more powerful than jack_client_new(). With it, + * clients may choose which of several servers to connect, and control + * whether and how to start the server automatically, if it was not + * already running. There is also an option for JACK to generate a + * unique client name, when necessary. + * + * @param client_name of at most jack_client_name_size() characters. + * The name scope is local to each server. Unless forbidden by the + * @ref JackUseExactName option, the server will modify this name to + * create a unique variant, if needed. + * + * @param options formed by OR-ing together @ref JackOptions bits. + * Only the @ref JackOpenOptions bits are allowed. + * + * @param status (if non-NULL) an address for JACK to return + * information from the open operation. This status word is formed by + * OR-ing together the relevant @ref JackStatus bits. + * + * + * Optional parameters: depending on corresponding [@a options + * bits] additional parameters may follow @a status (in this order). + * + * @arg [@ref JackServerName] (char *) server_name selects + * from among several possible concurrent server instances. Server + * names are unique to each user. If unspecified, use "default" + * unless \$JACK_DEFAULT_SERVER is defined in the process environment. + * + * @return Opaque client handle if successful. If this is NULL, the + * open operation failed, @a *status includes @ref JackFailure and the + * caller is not a JACK client. + */ +jack_client_t * jack_client_open (const char *client_name, + jack_options_t options, + jack_status_t *status, ...); + +/** +* \bold THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN +* NEW JACK CLIENTS +* +*/ +jack_client_t * jack_client_new (const char *client_name); + +/** + * Disconnects an external client from a JACK server. + * + * @return 0 on success, otherwise a non-zero error code + */ +int jack_client_close (jack_client_t *client); + +/** + * @return the maximum number of characters in a JACK client name + * including the final NULL character. This value is a constant. + */ +int jack_client_name_size (void); + +/** + * @return pointer to actual client name. This is useful when @ref + * JackUseExactName is not specified on open and @ref + * JackNameNotUnique status was returned. In that case, the actual + * name will differ from the @a client_name requested. + */ +char * jack_get_client_name (jack_client_t *client); + +/** + * 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 must declare jack_initialize() and jack_finish() entry + * points, called at load and unload times. See inprocess.c for an + * example of how to write an internal client. + * + * @deprecated Please use jack_internal_client_load(). + * + * @param client_name of at most jack_client_name_size() characters. + * + * @param load_name of a shared object file containing the code for + * the new client. + * + * @param load_init an arbitary string passed to the jack_initialize() + * routine of the new client (may be NULL). + * + * @return 0 if successful. + */ +int jack_internal_client_new (const char *client_name, + const char *load_name, + const char *load_init); + +/** + * Remove an internal client from a JACK server. + * + * @deprecated Please use jack_internal_client_load(). + */ +void jack_internal_client_close (const char *client_name); + +/** + * Tell the Jack server that the program is ready to start processing + * audio. + * + * @return 0 on success, otherwise a non-zero error code + */ +int jack_activate (jack_client_t *client); + +/** + * Tell the Jack server to remove this @a client from the process + * graph. Also, disconnect all ports belonging to it, since inactive + * clients have no port connections. + * + * @return 0 on success, otherwise a non-zero error code + */ +int jack_deactivate (jack_client_t *client); + +/** + * @return pid of client. If not available, 0 will be returned. + */ +int jack_get_client_pid (const char *name); + +/** + * @return the pthread ID of the thread running the JACK client side + * code. + */ +pthread_t jack_client_thread_id (jack_client_t *); + +/*@}*/ + +/** + * @param client pointer to JACK client structure. + * + * Check if the JACK subsystem is running with -R (--realtime). + * + * @return 1 if JACK is running realtime, 0 otherwise + */ +int jack_is_realtime (jack_client_t *client); + +/** + * @defgroup NonCallbackAPI The non-callback API + * @{ + */ + +/** + * \bold THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN + * NEW JACK CLIENTS. + * + * It should be replace by use of @ jack_cycle_wait and @ jack_cycle_signal functions. + * + */ +jack_nframes_t jack_thread_wait (jack_client_t*, int status); + +/** + * Wait until this JACK client should process data. + * + * @param client - pointer to a JACK client structure + * + * @return the number of frames of data to process + */ +jack_nframes_t jack_cycle_wait (jack_client_t* client); + +/** + * Signal next clients in the graph. + * + * @param client - pointer to a JACK client structure + * @param status - if non-zero, calling thread should exit + */ +void jack_cycle_signal (jack_client_t* client, int status); + +/** + * Tell the Jack server to call @a thread_callback in the RT thread. + * Typical use are in conjunction with @a jack_cycle_wait and @ jack_cycle_signal functions. + * The code in the supplied function must be suitable for real-time + * execution. That means that it cannot call functions that might + * block for a long time. This includes malloc, free, printf, + * pthread_mutex_lock, sleep, wait, poll, select, pthread_join, + * pthread_cond_wait, etc, etc. See + * http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000 + * for more information. + * + * NOTE: this function cannot be called while the client is activated + * (after jack_activate has been called.) + * + * @return 0 on success, otherwise a non-zero error code. +*/ +int jack_set_process_thread(jack_client_t* client, JackThreadCallback thread_callback, void *arg); + +/*@}*/ + +/** + * @defgroup ClientCallbacks Setting Client Callbacks + * @{ + */ + +/** + * Tell JACK to call @a thread_init_callback once just after + * the creation of the thread in which all other callbacks + * will be handled. + * + * The code in the supplied function does not need to be + * suitable for real-time execution. + * + * NOTE: this function cannot be called while the client is activated + * (after jack_activate has been called.) + * + * @return 0 on success, otherwise a non-zero error code, causing JACK + * to remove that client from the process() graph. + */ +int jack_set_thread_init_callback (jack_client_t *client, + JackThreadInitCallback thread_init_callback, + void *arg); + +/** + * @param client pointer to JACK client structure. + * @param function The jack_shutdown function pointer. + * @param arg The arguments for the jack_shutdown function. + * + * Register a function (and argument) to be called if and when the + * JACK server shuts down the client thread. The function must + * be written as if it were an asynchonrous POSIX signal + * handler --- use only async-safe functions, and remember that it + * is executed from another thread. A typical function might + * set a flag or write to a pipe so that the rest of the + * application knows that the JACK client thread has shut + * down. + * + * NOTE: clients do not need to call this. It exists only + * to help more complex clients understand what is going + * on. It should be called before jack_client_activate(). + */ +void jack_on_shutdown (jack_client_t *client, + JackShutdownCallback shutdown_callback, void *arg); + +/** + * Tell the Jack server to call @a process_callback whenever there is + * work be done, passing @a arg as the second argument. + * + * The code in the supplied function must be suitable for real-time + * execution. That means that it cannot call functions that might + * block for a long time. This includes malloc, free, printf, + * pthread_mutex_lock, sleep, wait, poll, select, pthread_join, + * pthread_cond_wait, etc, etc. See + * http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000 + * for more information. + * + * NOTE: this function cannot be called while the client is activated + * (after jack_activate has been called.) + * + * @return 0 on success, otherwise a non-zero error code. + */ +int jack_set_process_callback (jack_client_t *client, + JackProcessCallback process_callback, + void *arg); + +/** + * Tell the Jack server to call @a freewheel_callback + * whenever we enter or leave "freewheel" mode, passing @a + * arg as the second argument. The first argument to the + * callback will be non-zero if JACK is entering freewheel + * mode, and zero otherwise. + * + * All "notification events" are received in a seperated non RT thread, + * the code in the supplied function does not need to be + * suitable for real-time execution. + * + * NOTE: this function cannot be called while the client is activated + * (after jack_activate has been called.) + * + * @return 0 on success, otherwise a non-zero error code. + */ +int jack_set_freewheel_callback (jack_client_t *client, + JackFreewheelCallback freewheel_callback, + void *arg); + +/** + * Tell JACK to call @a bufsize_callback whenever the size of the the + * buffer that will be passed to the @a process_callback is about to + * change. Clients that depend on knowing the buffer size must supply + * a @a bufsize_callback before activating themselves. + * + * All "notification events" are received in a seperated non RT thread, + * the code in the supplied function does not need to be + * suitable for real-time execution. + * + * NOTE: this function cannot be called while the client is activated + * (after jack_activate has been called.) + * + * @param client pointer to JACK client structure. + * @param bufsize_callback function to call when the buffer size changes. + * @param arg argument for @a bufsize_callback. + * + * @return 0 on success, otherwise a non-zero error code + */ +int jack_set_buffer_size_callback (jack_client_t *client, + JackBufferSizeCallback bufsize_callback, + void *arg); - /** - * Note: More documentation can be found in jack/types.h. - */ - - /** - * Call this function to get version of the JACK, in form of several numbers - * - * @param major_ptr pointer to variable receiving major version of JACK. - * - * @param minor_ptr pointer to variable receiving minor version of JACK. - * - * @param major_ptr pointer to variable receiving micro version of JACK. - * - * @param major_ptr pointer to variable receiving protocol version of JACK. - * - */ - void - jack_get_version( - int *major_ptr, - int *minor_ptr, - int *micro_ptr, - int *proto_ptr); - - /** - * Call this function to get version of the JACK, in form of a string - * - * @return Human readable string describing JACK version being used. - * - */ - const char * - jack_get_version_string(); - - /** - * Open an external client session with a JACK server. This interface - * is more complex but more powerful than jack_client_new(). With it, - * clients may choose which of several servers to connect, and control - * whether and how to start the server automatically, if it was not - * already running. There is also an option for JACK to generate a - * unique client name, when necessary. - * - * @param client_name of at most jack_client_name_size() characters. - * The name scope is local to each server. Unless forbidden by the - * @ref JackUseExactName option, the server will modify this name to - * create a unique variant, if needed. - * - * @param options formed by OR-ing together @ref JackOptions bits. - * Only the @ref JackOpenOptions bits are allowed. - * - * @param status (if non-NULL) an address for JACK to return - * information from the open operation. This status word is formed by - * OR-ing together the relevant @ref JackStatus bits. - * - * - * Optional parameters: depending on corresponding [@a options - * bits] additional parameters may follow @a status (in this order). - * - * @arg [@ref JackServerName] (char *) server_name selects - * from among several possible concurrent server instances. Server - * names are unique to each user. If unspecified, use "default" - * unless \$JACK_DEFAULT_SERVER is defined in the process environment. - * - * @return Opaque client handle if successful. If this is NULL, the - * open operation failed, @a *status includes @ref JackFailure and the - * caller is not a JACK client. - */ - jack_client_t * jack_client_open (const char *client_name, - jack_options_t options, - jack_status_t *status, ...); - - /** - * \bold THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN - * NEW JACK CLIENTS - * - */ - jack_client_t * jack_client_new (const char *client_name); - - /** - * Disconnects an external client from a JACK server. - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_client_close (jack_client_t *client); - - /** - * @return the maximum number of characters in a JACK client name - * including the final NULL character. This value is a constant. - */ - int jack_client_name_size (void); - - /** - * @return pointer to actual client name. This is useful when @ref - * JackUseExactName is not specified on open and @ref - * JackNameNotUnique status was returned. In that case, the actual - * name will differ from the @a client_name requested. - */ - char * jack_get_client_name (jack_client_t *client); - - /** - * @return pid of client. If not available, 0 will be returned. - */ - int jack_get_client_pid (const char *name); - - /** - * 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 must declare jack_initialize() and jack_finish() entry - * points, called at load and unload times. See inprocess.c for an - * example of how to write an internal client. - * - * @deprecated Please use jack_internal_client_load(). - * - * @param client_name of at most jack_client_name_size() characters. - * - * @param load_name of a shared object file containing the code for - * the new client. - * - * @param load_init an arbitary string passed to the jack_initialize() - * routine of the new client (may be NULL). - * - * @return 0 if successful. - */ - int jack_internal_client_new (const char *client_name, - const char *load_name, - const char *load_init); - - /** - * Remove an internal client from a JACK server. - * - * @deprecated Please use jack_internal_client_load(). - */ - void jack_internal_client_close (const char *client_name); - - /** - * @param client pointer to JACK client structure. - * - * Check if the JACK subsystem is running with -R (--realtime). - * - * @return 1 if JACK is running realtime, 0 otherwise - */ - int jack_is_realtime (jack_client_t *client); - - /** - * @param client pointer to JACK client structure. - * @param function The jack_shutdown function pointer. - * @param arg The arguments for the jack_shutdown function. - * - * Register a function (and argument) to be called if and when the - * JACK server shuts down the client thread. The function must - * be written as if it were an asynchonrous POSIX signal - * handler --- use only async-safe functions, and remember that it - * is executed from another thread. A typical function might - * set a flag or write to a pipe so that the rest of the - * application knows that the JACK client thread has shut - * down. - * - * NOTE: clients do not need to call this. It exists only - * to help more complex clients understand what is going - * on. It should be called before jack_client_activate(). - */ - void jack_on_shutdown (jack_client_t *client, - JackShutdownCallback shutdown_callback, void *arg); - - /** - * Tell the Jack server to call @a process_callback whenever there is - * work be done, passing @a arg as the second argument. - * - * The code in the supplied function must be suitable for real-time - * execution. That means that it cannot call functions that might - * block for a long time. This includes malloc, free, printf, - * pthread_mutex_lock, sleep, wait, poll, select, pthread_join, - * pthread_cond_wait, etc, etc. See - * http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000 - * for more information. - * - * NOTE: this function cannot be called while the client is activated - * (after jack_activate has been called.) - * - * @return 0 on success, otherwise a non-zero error code. - */ - int jack_set_process_callback (jack_client_t *client, - JackProcessCallback process_callback, +/** + * Tell the Jack server to call @a srate_callback whenever the system + * sample rate changes. + * + * All "notification events" are received in a seperated non RT thread, + * the code in the supplied function does not need to be + * suitable for real-time execution. + * + * NOTE: this function cannot be called while the client is activated + * (after jack_activate has been called.) + * + * @return 0 on success, otherwise a non-zero error code + */ +int jack_set_sample_rate_callback (jack_client_t *client, + JackSampleRateCallback srate_callback, void *arg); - /** - * \bold THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN - * NEW JACK CLIENTS. - * - * It should be replace by use of @ jack_cycle_wait and @ jack_cycle_signal functions. - * - */ - jack_nframes_t jack_thread_wait (jack_client_t*, int status); - - /** - * Wait until this JACK client should process data. - * - * @param client - pointer to a JACK client structure - * - * @return the number of frames of data to process - */ - jack_nframes_t jack_cycle_wait (jack_client_t* client); - - /** - * Signal next clients in the graph. - * - * @param client - pointer to a JACK client structure - * @param status - if non-zero, calling thread should exit - */ - void jack_cycle_signal (jack_client_t* client, int status); - - /** - * Tell the Jack server to call @a thread_callback in the RT thread. - * Typical use are in conjunction with @a jack_cycle_wait and @ jack_cycle_signal functions. - * The code in the supplied function must be suitable for real-time - * execution. That means that it cannot call functions that might - * block for a long time. This includes malloc, free, printf, - * pthread_mutex_lock, sleep, wait, poll, select, pthread_join, - * pthread_cond_wait, etc, etc. See - * http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000 - * for more information. - * - * NOTE: this function cannot be called while the client is activated - * (after jack_activate has been called.) - * - * @return 0 on success, otherwise a non-zero error code. - */ - int jack_set_process_thread(jack_client_t* client, JackThreadCallback thread_callback, void *arg); - - /** - * Tell JACK to call @a thread_init_callback once just after - * the creation of the thread in which all other callbacks - * will be handled. - * - * The code in the supplied function does not need to be - * suitable for real-time execution. - * - * NOTE: this function cannot be called while the client is activated - * (after jack_activate has been called.) - * - * @return 0 on success, otherwise a non-zero error code, causing JACK - * to remove that client from the process() graph. - */ - int jack_set_thread_init_callback (jack_client_t *client, - JackThreadInitCallback thread_init_callback, - void *arg); - - /** - * Tell the Jack server to call @a freewheel_callback - * whenever we enter or leave "freewheel" mode, passing @a - * arg as the second argument. The first argument to the - * callback will be non-zero if JACK is entering freewheel - * mode, and zero otherwise. - * - * All "notification events" are received in a seperated non RT thread, - * the code in the supplied function does not need to be - * suitable for real-time execution. - * - * NOTE: this function cannot be called while the client is activated - * (after jack_activate has been called.) - * - * @return 0 on success, otherwise a non-zero error code. - */ - int jack_set_freewheel_callback (jack_client_t *client, - JackFreewheelCallback freewheel_callback, - void *arg); - - /** - * Start/Stop JACK's "freewheel" mode. - * - * When in "freewheel" mode, JACK no longer waits for - * any external event to begin the start of the next process - * cycle. - * - * As a result, freewheel mode causes "faster than realtime" - * execution of a JACK graph. If possessed, real-time - * scheduling is dropped when entering freewheel mode, and - * if appropriate it is reacquired when stopping. - * - * IMPORTANT: on systems using capabilities to provide real-time - * scheduling (i.e. Linux kernel 2.4), if onoff is zero, this function - * must be called from the thread that originally called jack_activate(). - * This restriction does not apply to other systems (e.g. Linux kernel 2.6 - * or OS X). - * - * @param client pointer to JACK client structure - * @param onoff if non-zero, freewheel mode starts. Otherwise - * freewheel mode ends. - * - * @return 0 on success, otherwise a non-zero error code. - */ - int jack_set_freewheel(jack_client_t* client, int onoff); - - /** - * Change the buffer size passed to the @a process_callback. - * - * This operation stops the JACK engine process cycle, then calls all - * registered @a bufsize_callback functions before restarting the - * process cycle. This will cause a gap in the audio flow, so it - * should only be done at appropriate stopping points. - * - * @see jack_set_buffer_size_callback() - * - * @param client pointer to JACK client structure. - * @param nframes new buffer size. Must be a power of two. - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_set_buffer_size (jack_client_t *client, jack_nframes_t nframes); - - /** - * Tell JACK to call @a bufsize_callback whenever the size of the the - * buffer that will be passed to the @a process_callback is about to - * change. Clients that depend on knowing the buffer size must supply - * a @a bufsize_callback before activating themselves. - * - * All "notification events" are received in a seperated non RT thread, - * the code in the supplied function does not need to be - * suitable for real-time execution. - * - * NOTE: this function cannot be called while the client is activated - * (after jack_activate has been called.) - * - * @param client pointer to JACK client structure. - * @param bufsize_callback function to call when the buffer size changes. - * @param arg argument for @a bufsize_callback. - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_set_buffer_size_callback (jack_client_t *client, - JackBufferSizeCallback bufsize_callback, - void *arg); - - /** - * Tell the Jack server to call @a srate_callback whenever the system - * sample rate changes. - * - * All "notification events" are received in a seperated non RT thread, - * the code in the supplied function does not need to be - * suitable for real-time execution. - * - * NOTE: this function cannot be called while the client is activated - * (after jack_activate has been called.) - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_set_sample_rate_callback (jack_client_t *client, - JackSampleRateCallback srate_callback, - void *arg); - - /** - * Tell the JACK server to call @a registration_callback whenever a - * port is registered or unregistered, passing @a arg as a parameter. - * - * All "notification events" are received in a seperated non RT thread, - * the code in the supplied function does not need to be - * suitable for real-time execution. - * - * NOTE: this function cannot be called while the client is activated - * (after jack_activate has been called.) - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_set_client_registration_callback (jack_client_t *, - JackClientRegistrationCallback - registration_callback, void *arg); - - /** - * Tell the JACK server to call @a registration_callback whenever a - * port is registered or unregistered, passing @a arg as a parameter. - * - * All "notification events" are received in a seperated non RT thread, - * the code in the supplied function does not need to be - * suitable for real-time execution. - * - * NOTE: this function cannot be called while the client is activated - * (after jack_activate has been called.) - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_set_port_registration_callback (jack_client_t *, - JackPortRegistrationCallback - registration_callback, void *arg); - - /** - * Tell the JACK server to call @a connect_callback whenever a - * port is connected or disconnected, passing @a arg as a parameter. - * - * All "notification events" are received in a seperated non RT thread, - * the code in the supplied function does not need to be - * suitable for real-time execution. - * - * NOTE: this function cannot be called while the client is activated - * (after jack_activate has been called.) - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_set_port_connect_callback (jack_client_t *, - JackPortConnectCallback - connect_callback, void *arg); - - /** - * Tell the JACK server to call @a rename_callback whenever a - * port is renamed, passing @a arg as a parameter. - * - * All "notification events" are received in a seperated non RT thread, - * the code in the supplied function does not need to be - * suitable for real-time execution. - * - * NOTE: this function cannot be called while the client is activated - * (after jack_activate has been called.) - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_set_port_rename_callback (jack_client_t *, - JackPortRenameCallback - rename_callback, void *arg); - - /** - * Tell the JACK server to call @a graph_callback whenever the - * processing graph is reordered, passing @a arg as a parameter. - * - * All "notification events" are received in a seperated non RT thread, - * the code in the supplied function does not need to be - * suitable for real-time execution. - * - * NOTE: this function cannot be called while the client is activated - * (after jack_activate has been called.) - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_set_graph_order_callback (jack_client_t *, - JackGraphOrderCallback graph_callback, - void *); - - /** - * Tell the JACK server to call @a xrun_callback whenever there is a - * xrun, passing @a arg as a parameter. - * - * All "notification events" are received in a seperated non RT thread, - * the code in the supplied function does not need to be - * suitable for real-time execution. - * - * NOTE: this function cannot be called while the client is activated - * (after jack_activate has been called.) - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_set_xrun_callback (jack_client_t *, - JackXRunCallback xrun_callback, void *arg); - - /** - * Tell the Jack server that the program is ready to start processing - * audio. - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_activate (jack_client_t *client); - - /** - * Tell the Jack server to remove this @a client from the process - * graph. Also, disconnect all ports belonging to it, since inactive - * clients have no port connections. - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_deactivate (jack_client_t *client); - - /** - * Create a new port for the client. This is an object used for moving - * data of any type in or out of the client. Ports may be connected - * in various ways. - * - * Each port has a short name. The port's full name contains the name - * of the client concatenated with a colon (:) followed by its short - * name. The jack_port_name_size() is the maximum length of this full - * name. Exceeding that will cause the port registration to fail and - * return NULL. - * - * All ports have a type, which may be any non-NULL and non-zero - * length string, passed as an argument. Some port types are built - * into the JACK API, currently only JACK_DEFAULT_AUDIO_TYPE. - * - * @param client pointer to JACK client structure. - * @param port_name non-empty short name for the new port (not - * including the leading @a "client_name:"). - * @param port_type port type name. If longer than - * jack_port_type_size(), only that many characters are significant. - * @param flags @ref JackPortFlags bit mask. - * @param buffer_size must be non-zero if this is not a built-in @a - * port_type. Otherwise, it is ignored. - * - * @return jack_port_t pointer on success, otherwise NULL. - */ - jack_port_t * jack_port_register (jack_client_t *client, - const char *port_name, - const char *port_type, - unsigned long flags, - unsigned long buffer_size); - - /** - * Remove the port from the client, disconnecting any existing - * connections. - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_port_unregister (jack_client_t *, jack_port_t *); - - /** - * This returns a pointer to the memory area associated with the - * specified port. For an output port, it will be a memory area - * that can be written to; for an input port, it will be an area - * containing the data from the port's connection(s), or - * zero-filled. if there are multiple inbound connections, the data - * will be mixed appropriately. - * - * FOR OUTPUT PORTS ONLY : DEPRECATED in Jack 2.0 !! - * --------------------------------------------------- - * You may cache the value returned, but only between calls to - * your "blocksize" callback. For this reason alone, you should - * either never cache the return value or ensure you have - * a "blocksize" callback and be sure to invalidate the cached - * address from there. - * - * Caching output ports is DEPRECATED in Jack 2.0, due to some new optimization (like "pipelining"). - * Port buffers have to be retrieved in each callback for proper functionning. - */ - void * jack_port_get_buffer (jack_port_t *, jack_nframes_t); - - /** - * @return the full name of the jack_port_t (including the @a - * "client_name:" prefix). - * - * @see jack_port_name_size(). - */ - const char * jack_port_name (const jack_port_t *port); - - /** - * @return the short name of the jack_port_t (not including the @a - * "client_name:" prefix). - * - * @see jack_port_name_size(). - */ - const char * jack_port_short_name (const jack_port_t *port); - - /** - * @return the @ref JackPortFlags of the jack_port_t. - */ - int jack_port_flags (const jack_port_t *port); - - /** - * @return the @a port type, at most jack_port_type_size() characters - * including a final NULL. - */ - const char * jack_port_type (const jack_port_t *port); - - /** - * @return the @a port type id. - */ - jack_port_type_id_t jack_port_type_id (const jack_port_t *port); - - /** - * @return TRUE if the jack_port_t belongs to the jack_client_t. - */ - int jack_port_is_mine (const jack_client_t *, const jack_port_t *port); - - /** - * @return number of connections to or from @a port. - * - * @pre The calling client must own @a port. - */ - int jack_port_connected (const jack_port_t *port); - - /** - * @return TRUE if the locally-owned @a port is @b directly connected - * to the @a port_name. - * - * @see jack_port_name_size() - */ - int jack_port_connected_to (const jack_port_t *port, - const char *port_name); - - /** - * @return a null-terminated array of full port names to which the @a - * port is connected. If none, returns NULL. - * - * The caller is responsible for calling free(3) on any non-NULL - * returned value. - * - * @param port locally owned jack_port_t pointer. - * - * @see jack_port_name_size(), jack_port_get_all_connections() - */ - const char ** jack_port_get_connections (const jack_port_t *port); - - /** - * @return a null-terminated array of full port names to which the @a - * port is connected. If none, returns NULL. - * - * The caller is responsible for calling free(3) on any non-NULL - * returned value. - * - * This differs from jack_port_get_connections() in two important - * respects: - * - * 1) You may not call this function from code that is - * executed in response to a JACK event. For example, - * you cannot use it in a GraphReordered handler. - * - * 2) You need not be the owner of the port to get information - * about its connections. - * - * @see jack_port_name_size() - */ - const char ** jack_port_get_all_connections (const jack_client_t *client, - const jack_port_t *port); - - /** - * A client may call this on a pair of its own ports to - * semi-permanently wire them together. This means that - * a client that wants to direct-wire an input port to - * an output port can call this and then no longer - * have to worry about moving data between them. Any data - * arriving at the input port will appear automatically - * at the output port. - * - * The 'destination' port must be an output port. The 'source' - * port must be an input port. Both ports must belong to - * the same client. You cannot use this to tie ports between - * clients. That is what a connection is for. - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_port_tie (jack_port_t *src, jack_port_t *dst); - - /** - * This undoes the effect of jack_port_tie(). The port - * should be same as the 'destination' port passed to - * jack_port_tie(). - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_port_untie (jack_port_t *port); - - /** - * @return the time (in frames) between data being available or - * delivered at/to a port, and the time at which it arrived at or is - * delivered to the "other side" of the port. E.g. for a physical - * audio output port, this is the time between writing to the port and - * when the signal will leave the connector. For a physical audio - * input port, this is the time between the sound arriving at the - * connector and the corresponding frames being readable from the - * port. - */ - jack_nframes_t jack_port_get_latency (jack_port_t *port); - - /** - * The maximum of the sum of the latencies in every - * connection path that can be drawn between the port and other - * ports with the @ref JackPortIsTerminal flag set. - */ - jack_nframes_t jack_port_get_total_latency (jack_client_t *, - jack_port_t *port); - - /** - * The port latency is zero by default. Clients that control - * physical hardware with non-zero latency should call this - * to set the latency to its correct value. Note that the value - * should include any systemic latency present "outside" the - * physical hardware controlled by the client. For example, - * for a client controlling a digital audio interface connected - * to an external digital converter, the latency setting should - * include both buffering by the audio interface *and* the converter. - */ - void jack_port_set_latency (jack_port_t *, jack_nframes_t); - - /** - * Request a complete recomputation of a port's total latency. This - * can be called by a client that has just changed the internal - * latency of its port using @function jack_port_set_latency - * and wants to ensure that all signal pathways in the graph - * are updated with respect to the values that will be returned - * by @function jack_port_get_total_latency. - * - * @return zero for successful execution of the request. non-zero - * otherwise. - */ - int jack_recompute_total_latency (jack_client_t*, jack_port_t* port); - - /** - * Request a complete recomputation of all port latencies. This - * can be called by a client that has just changed the internal - * latency of its port using @function jack_port_set_latency - * and wants to ensure that all signal pathways in the graph - * are updated with respect to the values that will be returned - * by @function jack_port_get_total_latency. It allows a client - * to change multiple port latencies without triggering a - * recompute for each change. - * - * @return zero for successful execution of the request. non-zero - * otherwise. - */ - int jack_recompute_total_latencies (jack_client_t*); - - /** - * Modify a port's short name. May be called at any time. If the - * resulting full name (including the @a "client_name:" prefix) is - * longer than jack_port_name_size(), it will be truncated. - * - * @return 0 on success, otherwise a non-zero error code. - */ - int jack_port_set_name (jack_port_t *port, const char *port_name); - - /** - * Set @a alias as an alias for @a port. May be called at any time. - * If the alias is longer than jack_port_name_size(), it will be truncated. - * - * After a successful call, and until JACK exits or - * @function jack_port_unset_alias() is called, @alias may be - * used as a alternate name for the port. - * - * Ports can have up to two aliases - if both are already - * set, this function will return an error. - * - * @return 0 on success, otherwise a non-zero error code. - */ - int jack_port_set_alias (jack_port_t *port, const char *alias); - - /** - * Remove @a alias as an alias for @a port. May be called at any time. - * - * After a successful call, @a alias can no longer be - * used as a alternate name for the port. - * - * @return 0 on success, otherwise a non-zero error code. - */ - int jack_port_unset_alias (jack_port_t *port, const char *alias); - - /* - * Get any aliases known for @port. - * - * @return the number of aliases discovered for the port - */ - int jack_port_get_aliases (const jack_port_t *port, char* const aliases[2]); - - /** - * If @ref JackPortCanMonitor is set for this @a port, turn input - * monitoring on or off. Otherwise, do nothing. - */ - int jack_port_request_monitor (jack_port_t *port, int onoff); - - /** - * If @ref JackPortCanMonitor is set for this @a port_name, turn input - * monitoring on or off. Otherwise, do nothing. - * - * @return 0 on success, otherwise a non-zero error code. - * - * @see jack_port_name_size() - */ - int jack_port_request_monitor_by_name (jack_client_t *client, - const char *port_name, int onoff); - - /** - * If @ref JackPortCanMonitor is set for a port, this function turns - * on input monitoring if it was off, and turns it off if only one - * request has been made to turn it on. Otherwise it does nothing. - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_port_ensure_monitor (jack_port_t *port, int onoff); - - /** - * @return TRUE if input monitoring has been requested for @a port. - */ - int jack_port_monitoring_input (jack_port_t *port); - - /** - * Establish a connection between two ports. - * - * When a connection exists, data written to the source port will - * be available to be read at the destination port. - * - * @pre The port types must be identical. - * - * @pre The @ref JackPortFlags of the @a source_port must include @ref - * JackPortIsOutput. - * - * @pre The @ref JackPortFlags of the @a destination_port must include - * @ref JackPortIsInput. - * - * @return 0 on success, EEXIST if the connection is already made, - * otherwise a non-zero error code - */ - int jack_connect (jack_client_t *, - const char *source_port, - const char *destination_port); - - /** - * Remove a connection between two ports. - * - * @pre The port types must be identical. - * - * @pre The @ref JackPortFlags of the @a source_port must include @ref - * JackPortIsOutput. - * - * @pre The @ref JackPortFlags of the @a destination_port must include - * @ref JackPortIsInput. - * - * @return 0 on success, otherwise a non-zero error code - */ - int jack_disconnect (jack_client_t *, - const char *source_port, - const char *destination_port); - - /** - * Perform the same function as jack_disconnect() using port handles - * rather than names. This avoids the name lookup inherent in the - * name-based version. - * - * Clients connecting their own ports are likely to use this function, - * while generic connection clients (e.g. patchbays) would use - * jack_disconnect(). - */ - int jack_port_disconnect (jack_client_t *, jack_port_t *); - - /** - * @return the maximum number of characters in a full JACK port name - * including the final NULL character. This value is a constant. - * - * A port's full name contains the owning client name concatenated - * with a colon (:) followed by its short name and a NULL - * character. - */ - int jack_port_name_size(void); - - /** - * @return the maximum number of characters in a JACK port type name - * including the final NULL character. This value is a constant. - */ - int jack_port_type_size(void); - - /** - * @return the sample rate of the jack system, as set by the user when - * jackd was started. - */ - jack_nframes_t jack_get_sample_rate (jack_client_t *); - - /** - * @return the current maximum size that will ever be passed to the @a - * process_callback. It should only be used *before* the client has - * been activated. This size may change, clients that depend on it - * must register a @a bufsize_callback so they will be notified if it - * does. - * - * @see jack_set_buffer_size_callback() - */ - jack_nframes_t jack_get_buffer_size (jack_client_t *); - - /** - * @param port_name_pattern A regular expression used to select - * ports by name. If NULL or of zero length, no selection based - * on name will be carried out. - * @param type_name_pattern A regular expression used to select - * ports by type. If NULL or of zero length, no selection based - * on type will be carried out. - * @param flags A value used to select ports by their flags. - * If zero, no selection based on flags will be carried out. - * - * @return a NULL-terminated array of ports that match the specified - * arguments. The caller is responsible for calling free(3) any - * non-NULL returned value. - * - * @see jack_port_name_size(), jack_port_type_size() - */ - const char ** jack_get_ports (jack_client_t *, - const char *port_name_pattern, - const char *type_name_pattern, - unsigned long flags); - - /** - * @return address of the jack_port_t named @a port_name. - * - * @see jack_port_name_size() - */ - jack_port_t * jack_port_by_name (jack_client_t *, const char *port_name); - - /** - * @return address of the jack_port_t of a @a port_id. - */ - jack_port_t * jack_port_by_id (jack_client_t *client, - jack_port_id_t port_id); - - /** - * Old-style interface to become the timebase for the entire JACK - * subsystem. - * - * @deprecated This function still exists for compatibility with the - * earlier transport interface, but it does nothing. Instead, see - * transport.h and use jack_set_timebase_callback(). - * - * @return ENOSYS, function not implemented. - */ - int jack_engine_takeover_timebase (jack_client_t *); - - /** - * @return the time in frames that has passed since the JACK server - * began the current process cycle. - */ - jack_nframes_t jack_frames_since_cycle_start (const jack_client_t *); - - /** - * @return an estimate of the current time in frames. This is a - * running counter, no significance should be attached to its value, - * but it can be compared to a previously returned value. - */ - jack_nframes_t jack_frame_time (const jack_client_t *); - - /** - * @return the frame_time after the last processing of the graph - * this is only to be used from the process callback. - * - * This function can be used to put timestamps generated by - * jack_frame_time() in correlation to the current process cycle. - */ - jack_nframes_t jack_last_frame_time (const jack_client_t *client); - - /** - * @return estimated time in microseconds of the specified frame time - */ - jack_time_t jack_frames_to_time(const jack_client_t *client, jack_nframes_t); - - /** - * @return estimated time in frames for the specified system time. - */ - jack_nframes_t jack_time_to_frames(const jack_client_t *client, jack_time_t); - - /** - * @return return JACK's current system time in microseconds, - * using JACK clock source. - * - * The value returned is guaranteed to be monotonic, but not linear. - * - * This function is a client version of @function jack_get_microseconds(). - */ - jack_time_t jack_get_time(); - - /** - * @return the current CPU load estimated by JACK. This is a running - * average of the time it takes to execute a full process cycle for - * all clients as a percentage of the real time available per cycle - * determined by the buffer size and sample rate. - */ - float jack_cpu_load (jack_client_t *client); - - /** - * @return the pthread ID of the thread running the JACK client side - * code. - */ - pthread_t jack_client_thread_id (jack_client_t *); - - /** - * Display JACK error message. - * - * Set via jack_set_error_function(), otherwise a JACK-provided - * default will print @a msg (plus a newline) to stderr. - * - * @param msg error message text (no newline at end). - */ - extern void (*jack_error_callback)(const char *msg); - - /** - * Set the @ref jack_error_callback for error message display. - * - * The JACK library provides two built-in callbacks for this purpose: - * default_jack_error_callback() and silent_jack_error_callback(). - */ - void jack_set_error_function (void (*func)(const char *)); - - /** - * Display JACK info message. - * - * Set via jack_set_info_function(), otherwise a JACK-provided - * default will print @a msg (plus a newline) to stdout. - * - * @param msg info message text (no newline at end). - */ - extern void (*jack_info_callback)(const char *msg); - - /** - * Set the @ref jack_info_callback for info message display. - */ - void jack_set_info_function (void (*func)(const char *)); + +/** + * Tell the JACK server to call @a registration_callback whenever a + * port is registered or unregistered, passing @a arg as a parameter. + * + * All "notification events" are received in a seperated non RT thread, + * the code in the supplied function does not need to be + * suitable for real-time execution. + * + * NOTE: this function cannot be called while the client is activated + * (after jack_activate has been called.) + * + * @return 0 on success, otherwise a non-zero error code + */ +int jack_set_client_registration_callback (jack_client_t *, + JackClientRegistrationCallback + registration_callback, void *arg); + +/** + * Tell the JACK server to call @a registration_callback whenever a + * port is registered or unregistered, passing @a arg as a parameter. + * + * All "notification events" are received in a seperated non RT thread, + * the code in the supplied function does not need to be + * suitable for real-time execution. + * + * NOTE: this function cannot be called while the client is activated + * (after jack_activate has been called.) + * + * @return 0 on success, otherwise a non-zero error code + */ + int jack_set_port_registration_callback (jack_client_t *, + JackPortRegistrationCallback + registration_callback, void *arg); + + /** + * Tell the JACK server to call @a connect_callback whenever a + * port is connected or disconnected, passing @a arg as a parameter. + * + * All "notification events" are received in a seperated non RT thread, + * the code in the supplied function does not need to be + * suitable for real-time execution. + * + * NOTE: this function cannot be called while the client is activated + * (after jack_activate has been called.) + * + * @return 0 on success, otherwise a non-zero error code + */ +int jack_set_port_connect_callback (jack_client_t *, + JackPortConnectCallback + connect_callback, void *arg); + + /** + * Tell the JACK server to call @a rename_callback whenever a + * port is renamed, passing @a arg as a parameter. + * + * All "notification events" are received in a seperated non RT thread, + * the code in the supplied function does not need to be + * suitable for real-time execution. + * + * NOTE: this function cannot be called while the client is activated + * (after jack_activate has been called.) + * + * @return 0 on success, otherwise a non-zero error code + */ +int jack_set_port_rename_callback (jack_client_t *, + JackPortRenameCallback + rename_callback, void *arg); + +/** + * Tell the JACK server to call @a graph_callback whenever the + * processing graph is reordered, passing @a arg as a parameter. + * + * All "notification events" are received in a seperated non RT thread, + * the code in the supplied function does not need to be + * suitable for real-time execution. + * + * NOTE: this function cannot be called while the client is activated + * (after jack_activate has been called.) + * + * @return 0 on success, otherwise a non-zero error code + */ +int jack_set_graph_order_callback (jack_client_t *, + JackGraphOrderCallback graph_callback, + void *); + +/** + * Tell the JACK server to call @a xrun_callback whenever there is a + * xrun, passing @a arg as a parameter. + * + * All "notification events" are received in a seperated non RT thread, + * the code in the supplied function does not need to be + * suitable for real-time execution. + * + * NOTE: this function cannot be called while the client is activated + * (after jack_activate has been called.) + * + * @return 0 on success, otherwise a non-zero error code + */ +int jack_set_xrun_callback (jack_client_t *, + JackXRunCallback xrun_callback, void *arg); + +/*@}*/ + +/** + * @defgroup ServerControl Controlling & querying JACK server operation + * @{ + */ + +/** + * Start/Stop JACK's "freewheel" mode. + * + * When in "freewheel" mode, JACK no longer waits for + * any external event to begin the start of the next process + * cycle. + * + * As a result, freewheel mode causes "faster than realtime" + * execution of a JACK graph. If possessed, real-time + * scheduling is dropped when entering freewheel mode, and + * if appropriate it is reacquired when stopping. + * + * IMPORTANT: on systems using capabilities to provide real-time + * scheduling (i.e. Linux kernel 2.4), if onoff is zero, this function + * must be called from the thread that originally called jack_activate(). + * This restriction does not apply to other systems (e.g. Linux kernel 2.6 + * or OS X). + * + * @param client pointer to JACK client structure + * @param onoff if non-zero, freewheel mode starts. Otherwise + * freewheel mode ends. + * + * @return 0 on success, otherwise a non-zero error code. + */ +int jack_set_freewheel(jack_client_t* client, int onoff); + +/** + * Change the buffer size passed to the @a process_callback. + * + * This operation stops the JACK engine process cycle, then calls all + * registered @a bufsize_callback functions before restarting the + * process cycle. This will cause a gap in the audio flow, so it + * should only be done at appropriate stopping points. + * + * @see jack_set_buffer_size_callback() + * + * @param client pointer to JACK client structure. + * @param nframes new buffer size. Must be a power of two. + * + * @return 0 on success, otherwise a non-zero error code + */ +int jack_set_buffer_size (jack_client_t *client, jack_nframes_t nframes); + +/** + * @return the sample rate of the jack system, as set by the user when + * jackd was started. + */ +jack_nframes_t jack_get_sample_rate (jack_client_t *); + +/** + * @return the current maximum size that will ever be passed to the @a + * process_callback. It should only be used *before* the client has + * been activated. This size may change, clients that depend on it + * must register a @a bufsize_callback so they will be notified if it + * does. + * + * @see jack_set_buffer_size_callback() + */ +jack_nframes_t jack_get_buffer_size (jack_client_t *); + +/** + * Old-style interface to become the timebase for the entire JACK + * subsystem. + * + * @deprecated This function still exists for compatibility with the + * earlier transport interface, but it does nothing. Instead, see + * transport.h and use jack_set_timebase_callback(). + * + * @return ENOSYS, function not implemented. + */ +int jack_engine_takeover_timebase (jack_client_t *); + +/** + * @return the current CPU load estimated by JACK. This is a running + * average of the time it takes to execute a full process cycle for + * all clients as a percentage of the real time available per cycle + * determined by the buffer size and sample rate. + */ +float jack_cpu_load (jack_client_t *client); + +/*@}*/ + +/** + * @defgroup PortFunctions Creating & manipulating ports + * @{ + */ + +/** + * Create a new port for the client. This is an object used for moving + * data of any type in or out of the client. Ports may be connected + * in various ways. + * + * Each port has a short name. The port's full name contains the name + * of the client concatenated with a colon (:) followed by its short + * name. The jack_port_name_size() is the maximum length of this full + * name. Exceeding that will cause the port registration to fail and + * return NULL. + * + * All ports have a type, which may be any non-NULL and non-zero + * length string, passed as an argument. Some port types are built + * into the JACK API, currently only JACK_DEFAULT_AUDIO_TYPE. + * + * @param client pointer to JACK client structure. + * @param port_name non-empty short name for the new port (not + * including the leading @a "client_name:"). + * @param port_type port type name. If longer than + * jack_port_type_size(), only that many characters are significant. + * @param flags @ref JackPortFlags bit mask. + * @param buffer_size must be non-zero if this is not a built-in @a + * port_type. Otherwise, it is ignored. + * + * @return jack_port_t pointer on success, otherwise NULL. + */ +jack_port_t * jack_port_register (jack_client_t *client, + const char *port_name, + const char *port_type, + unsigned long flags, + unsigned long buffer_size); + +/** + * Remove the port from the client, disconnecting any existing + * connections. + * + * @return 0 on success, otherwise a non-zero error code + */ +int jack_port_unregister (jack_client_t *, jack_port_t *); + +/** + * This returns a pointer to the memory area associated with the + * specified port. For an output port, it will be a memory area + * that can be written to; for an input port, it will be an area + * containing the data from the port's connection(s), or + * zero-filled. if there are multiple inbound connections, the data + * will be mixed appropriately. + * + * FOR OUTPUT PORTS ONLY : DEPRECATED in Jack 2.0 !! + * --------------------------------------------------- + * You may cache the value returned, but only between calls to + * your "blocksize" callback. For this reason alone, you should + * either never cache the return value or ensure you have + * a "blocksize" callback and be sure to invalidate the cached + * address from there. + * + * Caching output ports is DEPRECATED in Jack 2.0, due to some new optimization (like "pipelining"). + * Port buffers have to be retrieved in each callback for proper functionning. + */ +void * jack_port_get_buffer (jack_port_t *, jack_nframes_t); + +/** + * @return the full name of the jack_port_t (including the @a + * "client_name:" prefix). + * + * @see jack_port_name_size(). + */ +const char * jack_port_name (const jack_port_t *port); + +/** + * @return the short name of the jack_port_t (not including the @a + * "client_name:" prefix). + * + * @see jack_port_name_size(). + */ +const char * jack_port_short_name (const jack_port_t *port); + +/** + * @return the @ref JackPortFlags of the jack_port_t. + */ +int jack_port_flags (const jack_port_t *port); + +/** + * @return the @a port type, at most jack_port_type_size() characters + * including a final NULL. + */ +const char * jack_port_type (const jack_port_t *port); + + /** + * @return the @a port type id. + */ +jack_port_type_id_t jack_port_type_id (const jack_port_t *port); + +/** + * @return TRUE if the jack_port_t belongs to the jack_client_t. + */ +int jack_port_is_mine (const jack_client_t *, const jack_port_t *port); + +/** + * @return number of connections to or from @a port. + * + * @pre The calling client must own @a port. + */ +int jack_port_connected (const jack_port_t *port); + +/** + * @return TRUE if the locally-owned @a port is @b directly connected + * to the @a port_name. + * + * @see jack_port_name_size() + */ +int jack_port_connected_to (const jack_port_t *port, + const char *port_name); + +/** + * @return a null-terminated array of full port names to which the @a + * port is connected. If none, returns NULL. + * + * The caller is responsible for calling free(3) on any non-NULL + * returned value. + * + * @param port locally owned jack_port_t pointer. + * + * @see jack_port_name_size(), jack_port_get_all_connections() + */ +const char ** jack_port_get_connections (const jack_port_t *port); + +/** + * @return a null-terminated array of full port names to which the @a + * port is connected. If none, returns NULL. + * + * The caller is responsible for calling free(3) on any non-NULL + * returned value. + * + * This differs from jack_port_get_connections() in two important + * respects: + * + * 1) You may not call this function from code that is + * executed in response to a JACK event. For example, + * you cannot use it in a GraphReordered handler. + * + * 2) You need not be the owner of the port to get information + * about its connections. + * + * @see jack_port_name_size() + */ +const char ** jack_port_get_all_connections (const jack_client_t *client, + const jack_port_t *port); + +/** + * + * @deprecated This function will be removed from a future version + * of JACK. Do not use it. There is no replacement. It has + * turned out to serve essentially no purpose in real-life + * JACK clients. + */ +int jack_port_tie (jack_port_t *src, jack_port_t *dst); + +/** + * + * @deprecated This function will be removed from a future version + * of JACK. Do not use it. There is no replacement. It has + * turned out to serve essentially no purpose in real-life + * JACK clients. + */ +int jack_port_untie (jack_port_t *port); + + /** + * @return the time (in frames) between data being available or + * delivered at/to a port, and the time at which it arrived at or is + * delivered to the "other side" of the port. E.g. for a physical + * audio output port, this is the time between writing to the port and + * when the signal will leave the connector. For a physical audio + * input port, this is the time between the sound arriving at the + * connector and the corresponding frames being readable from the + * port. + */ +jack_nframes_t jack_port_get_latency (jack_port_t *port); + +/** + * The maximum of the sum of the latencies in every + * connection path that can be drawn between the port and other + * ports with the @ref JackPortIsTerminal flag set. + */ +jack_nframes_t jack_port_get_total_latency (jack_client_t *, + jack_port_t *port); + +/** + * The port latency is zero by default. Clients that control + * physical hardware with non-zero latency should call this + * to set the latency to its correct value. Note that the value + * should include any systemic latency present "outside" the + * physical hardware controlled by the client. For example, + * for a client controlling a digital audio interface connected + * to an external digital converter, the latency setting should + * include both buffering by the audio interface *and* the converter. + */ +void jack_port_set_latency (jack_port_t *, jack_nframes_t); + +/** +* Request a complete recomputation of a port's total latency. This +* can be called by a client that has just changed the internal +* latency of its port using @function jack_port_set_latency +* and wants to ensure that all signal pathways in the graph +* are updated with respect to the values that will be returned +* by @function jack_port_get_total_latency. +* +* @return zero for successful execution of the request. non-zero +* otherwise. +*/ +int jack_recompute_total_latency (jack_client_t*, jack_port_t* port); + +/** +* Request a complete recomputation of all port latencies. This +* can be called by a client that has just changed the internal +* latency of its port using @function jack_port_set_latency +* and wants to ensure that all signal pathways in the graph +* are updated with respect to the values that will be returned +* by @function jack_port_get_total_latency. It allows a client +* to change multiple port latencies without triggering a +* recompute for each change. +* +* @return zero for successful execution of the request. non-zero +* otherwise. +*/ +int jack_recompute_total_latencies (jack_client_t*); + +/** + * Modify a port's short name. May be called at any time. If the + * resulting full name (including the @a "client_name:" prefix) is + * longer than jack_port_name_size(), it will be truncated. + * + * @return 0 on success, otherwise a non-zero error code. + */ +int jack_port_set_name (jack_port_t *port, const char *port_name); + +/** + * Set @a alias as an alias for @a port. May be called at any time. + * If the alias is longer than jack_port_name_size(), it will be truncated. + * + * After a successful call, and until JACK exits or + * @function jack_port_unset_alias() is called, @alias may be + * used as a alternate name for the port. + * + * Ports can have up to two aliases - if both are already + * set, this function will return an error. + * + * @return 0 on success, otherwise a non-zero error code. + */ +int jack_port_set_alias (jack_port_t *port, const char *alias); + +/** + * Remove @a alias as an alias for @a port. May be called at any time. + * + * After a successful call, @a alias can no longer be + * used as a alternate name for the port. + * + * @return 0 on success, otherwise a non-zero error code. + */ +int jack_port_unset_alias (jack_port_t *port, const char *alias); + +/* + * Get any aliases known for @port. + * + * @return the number of aliases discovered for the port + */ +int jack_port_get_aliases (const jack_port_t *port, char* const aliases[2]); + +/** + * If @ref JackPortCanMonitor is set for this @a port, turn input + * monitoring on or off. Otherwise, do nothing. + */ +int jack_port_request_monitor (jack_port_t *port, int onoff); + +/** + * If @ref JackPortCanMonitor is set for this @a port_name, turn input + * monitoring on or off. Otherwise, do nothing. + * + * @return 0 on success, otherwise a non-zero error code. + * + * @see jack_port_name_size() + */ +int jack_port_request_monitor_by_name (jack_client_t *client, + const char *port_name, int onoff); + +/** + * If @ref JackPortCanMonitor is set for a port, this function turns + * on input monitoring if it was off, and turns it off if only one + * request has been made to turn it on. Otherwise it does nothing. + * + * @return 0 on success, otherwise a non-zero error code + */ +int jack_port_ensure_monitor (jack_port_t *port, int onoff); + +/** + * @return TRUE if input monitoring has been requested for @a port. + */ +int jack_port_monitoring_input (jack_port_t *port); + +/** + * Establish a connection between two ports. + * + * When a connection exists, data written to the source port will + * be available to be read at the destination port. + * + * @pre The port types must be identical. + * + * @pre The @ref JackPortFlags of the @a source_port must include @ref + * JackPortIsOutput. + * + * @pre The @ref JackPortFlags of the @a destination_port must include + * @ref JackPortIsInput. + * + * @return 0 on success, EEXIST if the connection is already made, + * otherwise a non-zero error code + */ +int jack_connect (jack_client_t *, + const char *source_port, + const char *destination_port); + +/** + * Remove a connection between two ports. + * + * @pre The port types must be identical. + * + * @pre The @ref JackPortFlags of the @a source_port must include @ref + * JackPortIsOutput. + * + * @pre The @ref JackPortFlags of the @a destination_port must include + * @ref JackPortIsInput. + * + * @return 0 on success, otherwise a non-zero error code + */ +int jack_disconnect (jack_client_t *, + const char *source_port, + const char *destination_port); + +/** + * Perform the same function as jack_disconnect() using port handles + * rather than names. This avoids the name lookup inherent in the + * name-based version. + * + * Clients connecting their own ports are likely to use this function, + * while generic connection clients (e.g. patchbays) would use + * jack_disconnect(). + */ +int jack_port_disconnect (jack_client_t *, jack_port_t *); + +/** + * @return the maximum number of characters in a full JACK port name + * including the final NULL character. This value is a constant. + * + * A port's full name contains the owning client name concatenated + * with a colon (:) followed by its short name and a NULL + * character. + */ +int jack_port_name_size(void); + +/** + * @return the maximum number of characters in a JACK port type name + * including the final NULL character. This value is a constant. + */ +int jack_port_type_size(void); + +/*@}*/ + +/** + * @defgroup PortSearching Looking up ports + * @{ + */ + +/** + * @param port_name_pattern A regular expression used to select + * ports by name. If NULL or of zero length, no selection based + * on name will be carried out. + * @param type_name_pattern A regular expression used to select + * ports by type. If NULL or of zero length, no selection based + * on type will be carried out. + * @param flags A value used to select ports by their flags. + * If zero, no selection based on flags will be carried out. + * + * @return a NULL-terminated array of ports that match the specified + * arguments. The caller is responsible for calling free(3) any + * non-NULL returned value. + * + * @see jack_port_name_size(), jack_port_type_size() + */ +const char ** jack_get_ports (jack_client_t *, + const char *port_name_pattern, + const char *type_name_pattern, + unsigned long flags); + +/** + * @return address of the jack_port_t named @a port_name. + * + * @see jack_port_name_size() + */ +jack_port_t * jack_port_by_name (jack_client_t *, const char *port_name); + +/** + * @return address of the jack_port_t of a @a port_id. + */ +jack_port_t * jack_port_by_id (jack_client_t *client, + jack_port_id_t port_id); + +/*@}*/ + +/** + * @defgroup TimeFunctions Handling time + * @{ + */ + +/** + * @return the time in frames that has passed since the JACK server + * began the current process cycle. + */ +jack_nframes_t jack_frames_since_cycle_start (const jack_client_t *); + +/** + * @return an estimate of the current time in frames. This is a + * running counter, no significance should be attached to its value, + * but it can be compared to a previously returned value. + */ +jack_nframes_t jack_frame_time (const jack_client_t *); + +/** + * @return the frame_time after the last processing of the graph + * this is only to be used from the process callback. + * + * This function can be used to put timestamps generated by + * jack_frame_time() in correlation to the current process cycle. + */ +jack_nframes_t jack_last_frame_time (const jack_client_t *client); + +/** + * @return estimated time in microseconds of the specified frame time + */ +jack_time_t jack_frames_to_time(const jack_client_t *client, jack_nframes_t); + +/** + * @return estimated time in frames for the specified system time. + */ +jack_nframes_t jack_time_to_frames(const jack_client_t *client, jack_time_t); + +/** + * @return return JACK's current system time in microseconds, + * using JACK clock source. + * + * The value returned is guaranteed to be monotonic, but not linear. + * + * This function is a client version of @function jack_get_microseconds(). + */ +jack_time_t jack_get_time(); + +/*@}*/ + +/** + * @defgroup ErrorOutput Controlling error/information output + */ +/*@{*/ + +/** + * Display JACK error message. + * + * Set via jack_set_error_function(), otherwise a JACK-provided + * default will print @a msg (plus a newline) to stderr. + * + * @param msg error message text (no newline at end). + */ +extern void (*jack_error_callback)(const char *msg); + +/** + * Set the @ref jack_error_callback for error message display. + * + * The JACK library provides two built-in callbacks for this purpose: + * default_jack_error_callback() and silent_jack_error_callback(). + */ +void jack_set_error_function (void (*func)(const char *)); + +/** + * Display JACK info message. + * + * Set via jack_set_info_function(), otherwise a JACK-provided + * default will print @a msg (plus a newline) to stdout. + * + * @param msg info message text (no newline at end). + */ +extern void (*jack_info_callback)(const char *msg); + +/** + * Set the @ref jack_info_callback for info message display. + */ +void jack_set_info_function (void (*func)(const char *)); + +/*@}*/ #ifdef __cplusplus } diff --git a/common/jack/midiport.h b/common/jack/midiport.h index da574f8d..68841ccd 100644 --- a/common/jack/midiport.h +++ b/common/jack/midiport.h @@ -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 } diff --git a/common/jack/ringbuffer.h b/common/jack/ringbuffer.h index ba826858..a4bd824f 100644 --- a/common/jack/ringbuffer.h +++ b/common/jack/ringbuffer.h @@ -28,203 +28,203 @@ extern "C" #include - /** @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 + * 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); #ifdef __cplusplus } diff --git a/common/jack/statistics.h b/common/jack/statistics.h index b90c2117..28c270d0 100644 --- a/common/jack/statistics.h +++ b/common/jack/statistics.h @@ -28,27 +28,27 @@ extern "C" #include - /** - * @return the maximum delay reported by the backend since - * startup or reset. When compared to the period size in usecs, this - * can be used to estimate the ideal period size for a given setup. - */ - float jack_get_max_delayed_usecs (jack_client_t *client); - - /** - * @return the delay in microseconds due to the most recent XRUN - * occurrence. This probably only makes sense when called from a @ref - * JackXRunCallback defined using jack_set_xrun_callback(). - */ - float jack_get_xrun_delayed_usecs (jack_client_t *client); - - /** - * Reset the maximum delay counter. This would be useful - * to estimate the effect that a change to the configuration of a running - * system (e.g. toggling kernel preemption) has on the delay - * experienced by JACK, without having to restart the JACK engine. - */ - void jack_reset_max_delayed_usecs (jack_client_t *client); +/** + * @return the maximum delay reported by the backend since + * startup or reset. When compared to the period size in usecs, this + * can be used to estimate the ideal period size for a given setup. + */ +float jack_get_max_delayed_usecs (jack_client_t *client); + +/** + * @return the delay in microseconds due to the most recent XRUN + * occurrence. This probably only makes sense when called from a @ref + * JackXRunCallback defined using jack_set_xrun_callback(). + */ +float jack_get_xrun_delayed_usecs (jack_client_t *client); + +/** + * Reset the maximum delay counter. This would be useful + * to estimate the effect that a change to the configuration of a running + * system (e.g. toggling kernel preemption) has on the delay + * experienced by JACK, without having to restart the JACK engine. + */ +void jack_reset_max_delayed_usecs (jack_client_t *client); #ifdef __cplusplus } diff --git a/common/jack/thread.h b/common/jack/thread.h index 14066006..9ff84b98 100644 --- a/common/jack/thread.h +++ b/common/jack/thread.h @@ -27,74 +27,97 @@ extern "C" #include - /** @file thread.h - * - * Library functions to standardize thread creation for JACK and its - * clients. These interfaces hide some system variations in the - * handling of realtime scheduling and associated privileges. - */ - - /** - * Attempt to enable realtime scheduling for a thread. On some - * systems that may require special privileges. - * - * @param thread POSIX thread ID. - * @param priority requested thread priority. - * - * @returns 0, if successful; EPERM, if the calling process lacks - * required realtime privileges; otherwise some other error number. - */ - int jack_acquire_real_time_scheduling (pthread_t thread, int priority); - - /** - * Create a thread for JACK or one of its clients. The thread is - * created executing @a start_routine with @a arg as its sole - * argument. - * - * @param client the JACK client for whom the thread is being created. May be - * NULL if the client is being created within the JACK server. - * @param thread place to return POSIX thread ID. - * @param priority thread priority, if realtime. - * @param realtime true for the thread to use realtime scheduling. On - * some systems that may require special privileges. - * @param start_routine function the thread calls when it starts. - * @param arg parameter passed to the @a start_routine. - * - * @returns 0, if successful; otherwise some error number. - */ - int jack_client_create_thread (jack_client_t* client, - pthread_t *thread, - int priority, - int realtime, /* boolean */ - void *(*start_routine)(void*), - void *arg); - - /** - * Drop realtime scheduling for a thread. - * - * @param thread POSIX thread ID. - * - * @returns 0, if successful; otherwise an error number. - */ - int jack_drop_real_time_scheduling (pthread_t thread); - - /** - * Stop the thread, waiting for the thread handler to terminate. - * - * @param thread POSIX thread ID. - * - * @returns 0, if successful; otherwise an error number. - */ - int jack_client_stop_thread(jack_client_t* client, pthread_t thread); - - /** - * Cancel the thread then waits for the thread handler to terminate. - * - * @param thread POSIX thread ID. - * - * @returns 0, if successful; otherwise an error number. - */ - int jack_client_kill_thread(jack_client_t* client, pthread_t thread); +/** @file thread.h + * + * Library functions to standardize thread creation for JACK and its + * clients. These interfaces hide some system variations in the + * handling of realtime scheduling and associated privileges. + */ + +/** + * @defgroup ClientThreads Creating and managing client threads + * @{ + */ + + /** + * @returns if JACK is running with realtime scheduling, this returns + * the priority that any JACK-created client threads will run at. + * Otherwise returns -1. + */ + +int jack_client_real_time_priority (jack_client_t*); + +/** + * @returns if JACK is running with realtime scheduling, this returns + * the maximum priority that a JACK client thread should use if the thread + * is subject to realtime scheduling. Otherwise returns -1. + */ + +int jack_client_max_real_time_priority (jack_client_t*); + +/** + * Attempt to enable realtime scheduling for a thread. On some + * systems that may require special privileges. + * + * @param thread POSIX thread ID. + * @param priority requested thread priority. + * + * @returns 0, if successful; EPERM, if the calling process lacks + * required realtime privileges; otherwise some other error number. + */ +int jack_acquire_real_time_scheduling (pthread_t thread, int priority); + +/** + * Create a thread for JACK or one of its clients. The thread is + * created executing @a start_routine with @a arg as its sole + * argument. + * + * @param client the JACK client for whom the thread is being created. May be + * NULL if the client is being created within the JACK server. + * @param thread place to return POSIX thread ID. + * @param priority thread priority, if realtime. + * @param realtime true for the thread to use realtime scheduling. On + * some systems that may require special privileges. + * @param start_routine function the thread calls when it starts. + * @param arg parameter passed to the @a start_routine. + * + * @returns 0, if successful; otherwise some error number. + */ +int jack_client_create_thread (jack_client_t* client, + pthread_t *thread, + int priority, + int realtime, /* boolean */ + void *(*start_routine)(void*), + void *arg); + +/** + * Drop realtime scheduling for a thread. + * + * @param thread POSIX thread ID. + * + * @returns 0, if successful; otherwise an error number. + */ +int jack_drop_real_time_scheduling (pthread_t thread); + +/** + * Stop the thread, waiting for the thread handler to terminate. + * + * @param thread POSIX thread ID. + * + * @returns 0, if successful; otherwise an error number. + */ +int jack_client_stop_thread(jack_client_t* client, pthread_t thread); + +/** + * Cancel the thread then waits for the thread handler to terminate. + * + * @param thread POSIX thread ID. + * + * @returns 0, if successful; otherwise an error number. + */ + int jack_client_kill_thread(jack_client_t* client, pthread_t thread); + +/* @} */ #ifdef __cplusplus } diff --git a/common/jack/transport.h b/common/jack/transport.h index 923304e5..67bcaa2a 100644 --- a/common/jack/transport.h +++ b/common/jack/transport.h @@ -27,6 +27,11 @@ extern "C" { #include +/** + * @defgroup TransportControl Transport and Timebase control + * @{ + */ + /** * Called by the timebase master to release itself from that * responsibility. @@ -206,7 +211,7 @@ void jack_transport_start (jack_client_t *client); * @param client the JACK client structure. */ void jack_transport_stop (jack_client_t *client); - + /** * Gets the current transport info structure (deprecated). * @@ -232,6 +237,8 @@ void jack_get_transport_info (jack_client_t *client, void jack_set_transport_info (jack_client_t *client, jack_transport_info_t *tinfo); +/*@}*/ + #ifdef __cplusplus } #endif diff --git a/doxyfile b/doxyfile index 82d66b96..c86bb5dd 100644 --- a/doxyfile +++ b/doxyfile @@ -17,13 +17,13 @@ # The PROJECT_NAME tag is a single word (or a sequence of words surrounded # by quotes) that should identify the project. -PROJECT_NAME = "Jackdmp" +PROJECT_NAME = "Jack2" # The PROJECT_NUMBER tag can be used to enter a project or revision number. # This could be handy for archiving the generated documentation or # if some version control system is used. -PROJECT_NUMBER = 1.90 +PROJECT_NUMBER = 1.9.1 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) # base path where the generated documentation will be put.