Setting Client Callbacks

Modules
	Controlling & querying JACK server operation

Functions
int	jack_set_thread_init_callback (jack_client_t *client, JackThreadInitCallback thread_init_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT
void	jack_on_shutdown (jack_client_t *client, JackShutdownCallback function, void *arg) JACK_OPTIONAL_WEAK_EXPORT
void	jack_on_info_shutdown (jack_client_t *client, JackInfoShutdownCallback function, void *arg) JACK_WEAK_EXPORT
int	jack_set_process_callback (jack_client_t *client, JackProcessCallback process_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_freewheel_callback (jack_client_t *client, JackFreewheelCallback freewheel_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_buffer_size_callback (jack_client_t *client, JackBufferSizeCallback bufsize_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_sample_rate_callback (jack_client_t *client, JackSampleRateCallback srate_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_client_registration_callback (jack_client_t *, JackClientRegistrationCallback registration_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_port_registration_callback (jack_client_t *, JackPortRegistrationCallback registration_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_port_rename_callback (jack_client_t *, JackPortRenameCallback rename_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_port_connect_callback (jack_client_t *, JackPortConnectCallback connect_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_graph_order_callback (jack_client_t *, JackGraphOrderCallback graph_callback, void *) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_xrun_callback (jack_client_t *, JackXRunCallback xrun_callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT
int	jack_set_latency_callback (jack_client_t *, JackLatencyCallback latency_callback, void *) JACK_WEAK_EXPORT

Detailed Description

Function Documentation

jack_on_info_shutdown()

void jack_on_info_shutdown	(	jack_client_t *	client,
		JackInfoShutdownCallback	function,
		void *	arg
	)

Parameters

client	pointer to JACK client structure.
function	The jack_shutdown function pointer.
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().

NOTE: if a client calls this AND jack_on_shutdown(), then in the event of a client thread shutdown, the callback passed to this function will be called, and the one passed to jack_on_shutdown() will not.

jack_on_shutdown()

void jack_on_shutdown	(	jack_client_t *	client,
		JackShutdownCallback	function,
		void *	arg
	)

Parameters

client	pointer to JACK client structure.
function	The jack_shutdown function pointer.
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().

NOTE: if a client calls this AND jack_on_info_shutdown(), then the event of a client thread shutdown, the callback passed to this function will not be called, and the one passed to jack_on_info_shutdown() will.

jack_set_buffer_size_callback()

int jack_set_buffer_size_callback	(	jack_client_t *	client,
		JackBufferSizeCallback	bufsize_callback,
		void *	arg
	)

Tell JACK to call bufsize_callback whenever the size of the the buffer that will be passed to the process_callback is about to change. Clients that depend on knowing the buffer size must supply a bufsize_callback before activating themselves.

Parameters

client	pointer to JACK client structure.
bufsize_callback	function to call when the buffer size changes.
arg	argument for bufsize_callback.

Returns

0 on success, otherwise a non-zero error code

jack_set_client_registration_callback()

int jack_set_client_registration_callback	(	jack_client_t *	,
		JackClientRegistrationCallback	registration_callback,
		void *	arg
	)

Tell the JACK server to call registration_callback whenever a port is registered or unregistered, passing arg as a parameter.

Returns

0 on success, otherwise a non-zero error code

jack_set_freewheel_callback()

int jack_set_freewheel_callback	(	jack_client_t *	client,
		JackFreewheelCallback	freewheel_callback,
		void *	arg
	)

Tell the Jack server to call freewheel_callback whenever we enter or leave "freewheel" mode, passing arg as the second argument. The first argument to the callback will be non-zero if JACK is entering freewheel mode, and zero otherwise.

Returns

0 on success, otherwise a non-zero error code.

jack_set_graph_order_callback()

int jack_set_graph_order_callback	(	jack_client_t *	,
		JackGraphOrderCallback	graph_callback,
		void *
	)

Tell the JACK server to call graph_callback whenever the processing graph is reordered, passing arg as a parameter.

Returns

0 on success, otherwise a non-zero error code

jack_set_latency_callback()

int jack_set_latency_callback	(	jack_client_t *	,
		JackLatencyCallback	latency_callback,
		void *
	)

Tell the Jack server to call latency_callback whenever it is necessary to recompute the latencies for some or all Jack ports.

latency_callback will be called twice each time it is needed, once being passed JackCaptureLatency and once JackPlaybackLatency. See Managing and determining latency for the definition of each type of latency and related functions.

IMPORTANT: Most JACK clients do NOT need to register a latency callback.

Clients that meet any of the following conditions do NOT need to register a latency callback:

• have only input ports
• have only output ports
• their output is totally unrelated to their input
• their output is not delayed relative to their input (i.e. data that arrives in a given process() callback is processed and output again in the same callback)

Clients NOT registering a latency callback MUST also satisfy this condition:

• have no multiple distinct internal signal pathways

This means that if your client has more than 1 input and output port, and considers them always "correlated" (e.g. as a stereo pair), then there is only 1 (e.g. stereo) signal pathway through the client. This would be true, for example, of a stereo FX rack client that has a left/right input pair and a left/right output pair.

However, this is somewhat a matter of perspective. The same FX rack client could be connected so that its two input ports were connected to entirely separate sources. Under these conditions, the fact that the client does not register a latency callback MAY result in port latency values being incorrect.

Clients that do not meet any of those conditions SHOULD register a latency callback.

Another case is when a client wants to use jack_port_get_latency_range(), which only returns meaninful values when ports get connected and latency values change.

See the documentation for jack_port_set_latency_range() on how the callback should operate. Remember that the mode argument given to the latency callback will need to be passed into jack_port_set_latency_range()

Returns

0 on success, otherwise a non-zero error code

jack_set_port_connect_callback()

int jack_set_port_connect_callback	(	jack_client_t *	,
		JackPortConnectCallback	connect_callback,
		void *	arg
	)

Tell the JACK server to call connect_callback whenever a port is connected or disconnected, passing arg as a parameter.

Returns

0 on success, otherwise a non-zero error code

jack_set_port_registration_callback()

int jack_set_port_registration_callback	(	jack_client_t *	,
		JackPortRegistrationCallback	registration_callback,
		void *	arg
	)

Tell the JACK server to call registration_callback whenever a port is registered or unregistered, passing arg as a parameter.

Returns

0 on success, otherwise a non-zero error code

jack_set_port_rename_callback()

int jack_set_port_rename_callback	(	jack_client_t *	,
		JackPortRenameCallback	rename_callback,
		void *	arg
	)

Tell the JACK server to call rename_callback whenever a port is renamed, passing arg as a parameter.

Returns

0 on success, otherwise a non-zero error code

jack_set_process_callback()

int jack_set_process_callback	(	jack_client_t *	client,
		JackProcessCallback	process_callback,
		void *	arg
	)

Tell the Jack server to call process_callback whenever there is work be done, passing 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 all I/O functions (disk, TTY, network), malloc, free, printf, pthread_mutex_lock, sleep, wait, poll, select, pthread_join, pthread_cond_wait, etc, etc.

Returns

0 on success, otherwise a non-zero error code, causing JACK to remove that client from the process() graph.

jack_set_sample_rate_callback()

int jack_set_sample_rate_callback	(	jack_client_t *	client,
		JackSampleRateCallback	srate_callback,
		void *	arg
	)

Tell the Jack server to call srate_callback whenever the system sample rate changes.

Returns

0 on success, otherwise a non-zero error code

jack_set_thread_init_callback()

int jack_set_thread_init_callback	(	jack_client_t *	client,
		JackThreadInitCallback	thread_init_callback,
		void *	arg
	)

Tell JACK to call 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.

Returns

0 on success, otherwise a non-zero error code, causing JACK to remove that client from the process() graph.

jack_set_xrun_callback()

int jack_set_xrun_callback	(	jack_client_t *	,
		JackXRunCallback	xrun_callback,
		void *	arg
	)

Tell the JACK server to call xrun_callback whenever there is a xrun, passing arg as a parameter.

Returns

0 on success, otherwise a non-zero error code