Trait jack::JackHandler [−] [src]

pub trait JackHandler: Send {
    fn thread_init(&mut self) { ... }
    fn shutdown(&mut self, _status: ClientStatus, _reason: &str) { ... }
    fn process(&mut self, process_scope: &ProcessScope) -> JackControl { ... }
    fn freewheel(&mut self, _is_freewheel_enabled: bool) { ... }
    fn buffer_size(&mut self, _size: u32) -> JackControl { ... }
    fn sample_rate(&mut self, _srate: u32) -> JackControl { ... }
    fn client_registration(&mut self, _name: &str, _is_registered: bool) { ... }
    fn port_registration(&mut self, _port_id: u32, _is_registered: bool) { ... }
    fn port_rename(&mut self,
                   _port_id: u32,
                   _old_name: &str,
                   _new_name: &str)
                   -> JackControl { ... }
    fn ports_connected(&mut self,
                       _port_id_a: u32,
                       _port_id_b: u32,
                       _are_connected: bool) { ... }
    fn graph_reorder(&mut self) -> JackControl { ... }
    fn xrun(&mut self) -> JackControl { ... }
    fn latency(&mut self, _mode: LatencyType) { ... }
}

Specifies callbacks for JACK.

All callbacks happen on the same thread (not concurrently), unless otherwise stated.

TODO

  • convert C enum return values to Rust enums.

Provided Methods

Called just once after the creation of the thread in which all other callbacks will be handled.

It does not need to be suitable for real-time execution.

Called when the JACK server shuts down the client thread. The function must be written as if it were an asynchronous POSIX signal handler --- use only async-safe functions, and remember that it is executed from another thread. A typical funcion 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.

Called whenever there is work to be done.

It needs to 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.

Should return 0 on success, and non-zero on error.

Called whenever "freewheel" mode is entered or leaving.

Called whenever the size of the buffer that will be passed to process is about to change.

Called whenever the system sample rate changes.

Called whenever a client is registered or unregistered

Called whenever a port is registered or unregistered

Called whenever a port is renamed.

TODO

  • Possibly fix description, JACK API docs have same description for this as port registration.

Called whenever ports are connected/disconnected to/from each other.

Called whenever the processing graph is reordered.

Called whenever an xrun occurs.

An xrun is a buffer under or over run, which means some data has been missed.

Called whenever it is necessary to recompute the latencies for some or all JACK ports.

It will be called twice each time it is needed, once being passed CaptureLatency and once with `PlayBackLatency. See managing and determining latency for the definition of each type of latency and related functions. TODO: clear up the "see managing and ..." in the docstring.

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

Clients that meed 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 process 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.

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()

Implementors