0.2: add more handlers, fix panic unsoundness

- Not all the handlers are added yet. This is because I got bored.
- Panicking is now safe (still not a good idea, but safe) to do in
  callbacks. Yay!

Author: eeeeeta

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sqa-jack"
-version = "0.1.1"
+version = "0.2.0"
 description = "JACK bindings for Rust (part of the SQA project)"
 documentation = "https://docs.rs/sqa-jack"
 repository = "https://github.com/eeeeeta/sqa-jack"

src/handler.rs

@@ -1,4 +1,5 @@
 use *;
+use std::panic::{AssertUnwindSafe, catch_unwind};
 
 /// Context for some callbacks.
 pub struct JackCallbackContext {
@@ -33,6 +34,10 @@ pub enum JackControl {
     /// Stop processing.
     Stop = -1
 }
+/// Trait for an object that implements JACK callbacks.
+///
+/// Most of the default implementations return `JackControl::Continue` - however, **process() does not** - you
+/// must explicitly override this behaviour if you want to specify nothing for `process()`.
 pub trait JackHandler: Send {
     /// This function is called by the engine any time there is work to be done.
     /// Return `JackControl::Stop` to stop processing, otherwise return
@@ -53,34 +58,119 @@ pub trait JackHandler: Send {
     fn process(&mut self, _ctx: &JackCallbackContext) -> JackControl {
         JackControl::Stop
     }
+    /// This is called whenever the size of the the buffer that will be passed to the
+    /// `process()` function is about to change.
+    /// Clients that depend on knowing the buffer size must implement this callback.
+    fn buffer_size(&mut self, _new_size: jack_nframes_t) -> JackControl { JackControl::Continue }
+    /// Called whenever the system sample rate changes.
+    ///
+    /// Given that the JACK API exposes no way to change the sample rate, the library author
+    /// would like you to know that this is a decidedly rare occurence. Still, it's worth
+    /// being prepared ;)
+    fn sample_rate(&mut self, _new_rate: jack_nframes_t) -> JackControl { JackControl::Continue }
+    /// Called just once after the creation of the thread in which all other callbacks are
+    /// handled.
+    fn thread_init(&mut self) {  }
+    /// To be called if and when the JACK server shuts down the client thread.
+    fn shutdown(&mut self, _status: JackStatus, _reason: &str) { }
+    /// Called whenever a client is registered or unregistered.
+    ///
+    /// Use the `registered` argument to determine which it is.
+    fn client_registered(&mut self, _name: &str, _registered: bool) { }
+    /// Called when an XRUN (over- or under- run) occurs.
+    fn xrun(&mut self) -> JackControl { JackControl::Continue }
 }
+/*
+    /// Called whenever a port is registered or unregistered.
+    ///
+    /// Use the `registered` argument to determine which it is.
+    fn port_registered(&mut self, _port: JackPort, _registered: bool) { }
+    /// Called whenever a port is renamed.
+    fn port_renamed(&mut self, _port: JackPort, _old_name: &str, _new_name: &str) { }
+    /// Called whenever ports are connected or disconnected.
+    ///
+    /// Use the `connected` argument to determine which it is.
+    fn port_connected(&mut self, _from: JackPort, _to: JackPort, _connected: bool) { }
+    /// Called whenever the processing graph is reordered.
+    fn graph_reorder(&mut self) -> JackControl { JackControl::Continue }
+    /// Called when the JACK server starts or stops freewheeling.
+    ///
+    /// Use the `freewheel` argument to determine which it is.
+    fn freewheel(&mut self, _freewheel: bool) { }
+*/
 
 impl<F> JackHandler for F where F: FnMut(&JackCallbackContext) -> JackControl + Send + 'static {
     fn process(&mut self, ctx: &JackCallbackContext) -> JackControl {
         self(ctx)
     }
 }
+unsafe extern "C" fn buffer_size_callback<T>(frames: jack_nframes_t, user: *mut libc::c_void) -> libc::c_int where T: JackHandler {
+    let callbacks = &mut *(user as *mut T);
+    catch_unwind(AssertUnwindSafe(|| {
+        callbacks.buffer_size(frames) as _
+    })).unwrap_or(-1)
+}
+unsafe extern "C" fn sample_rate_callback<T>(frames: jack_nframes_t, user: *mut libc::c_void) -> libc::c_int where T: JackHandler {
+    let callbacks = &mut *(user as *mut T);
+    catch_unwind(AssertUnwindSafe(|| {
+        callbacks.sample_rate(frames) as _
+    })).unwrap_or(-1)
+}
+unsafe extern "C" fn client_registration_callback<T>(name: *const libc::c_char, register: libc::c_int, user: *mut libc::c_void) where T: JackHandler {
+    let callbacks = &mut *(user as *mut T);
+    let name = CStr::from_ptr(name);
+    let _ = catch_unwind(AssertUnwindSafe(|| {
+        callbacks.client_registered(&name.to_string_lossy(), register != 0)
+    }));
 
-extern "C" fn process_callback<T>(nframes: jack_nframes_t, user: *mut libc::c_void) -> i32 where T: JackHandler {
-    unsafe {
-        let callbacks = &mut *(user as *mut T);
-        let ctx = JackCallbackContext {
-            nframes: nframes
-        };
-        callbacks.process(&ctx) as i32
-    }
 }
+unsafe extern "C" fn info_shutdown_callback<T>(code: jack_status_t, reason: *const libc::c_char, user: *mut libc::c_void) where T: JackHandler {
+    let callbacks = &mut *(user as *mut T);
+    let code = JackStatus::from_bits_truncate(code);
+    let reason = CStr::from_ptr(reason);
+    let _ = catch_unwind(AssertUnwindSafe(|| {
+        callbacks.shutdown(code, &reason.to_string_lossy())
+    }));
 
+}
+unsafe extern "C" fn thread_init_callback<T>(user: *mut libc::c_void) where T: JackHandler {
+    let callbacks = &mut *(user as *mut T);
+    let _ = catch_unwind(AssertUnwindSafe(|| {
+        callbacks.thread_init()
+    }));
+}
+unsafe extern "C" fn process_callback<T>(nframes: jack_nframes_t, user: *mut libc::c_void) -> libc::c_int where T: JackHandler {
+    let callbacks = &mut *(user as *mut T);
+    let ctx = JackCallbackContext {
+        nframes: nframes
+    };
+    catch_unwind(AssertUnwindSafe(|| {
+        callbacks.process(&ctx) as _
+    })).unwrap_or(-1)
+}
+unsafe extern "C" fn xrun_callback<T>(user: *mut libc::c_void) -> libc::c_int where T: JackHandler {
+    let callbacks = &mut *(user as *mut T);
+    catch_unwind(AssertUnwindSafe(|| {
+        callbacks.xrun() as _
+    })).unwrap_or(-1)
+}
 pub fn set_handler<F>(conn: &mut JackConnection<Deactivated>, handler: F) -> JackResult<()> where F: JackHandler {
     let user_ptr = Box::into_raw(Box::new(handler));
     let user_ptr = user_ptr as *mut libc::c_void;
-    let code = unsafe {
-        jack_set_process_callback(conn.handle, Some(process_callback::<F>), user_ptr)
-    };
-    if code != 0 {
-        Err(ErrorKind::UnknownErrorCode("set_process_callback()", code))?
-    }
-    else {
-        Ok(())
+    unsafe {
+        let code = jack_set_process_callback(conn.handle, Some(process_callback::<F>), user_ptr);
+        if code != 0 { Err(ErrorKind::UnknownErrorCode("set_process_callback() - process", code))? }
+        let code = jack_set_thread_init_callback(conn.handle, Some(thread_init_callback::<F>), user_ptr);
+        if code != 0 { Err(ErrorKind::UnknownErrorCode("set_process_callback() - thread_init", code))? }
+        let code = jack_set_buffer_size_callback(conn.handle, Some(buffer_size_callback::<F>), user_ptr);
+        if code != 0 { Err(ErrorKind::UnknownErrorCode("set_process_callback() - buffer_size", code))? }
+        let code = jack_set_sample_rate_callback(conn.handle, Some(sample_rate_callback::<F>), user_ptr);
+        if code != 0 { Err(ErrorKind::UnknownErrorCode("set_process_callback() - sample_rate", code))? }
+        let code = jack_set_xrun_callback(conn.handle, Some(xrun_callback::<F>), user_ptr);
+        if code != 0 { Err(ErrorKind::UnknownErrorCode("set_process_callback() - xrun", code))? }
+        let code = jack_set_client_registration_callback(conn.handle, Some(client_registration_callback::<F>), user_ptr);
+        if code != 0 { Err(ErrorKind::UnknownErrorCode("set_process_callback() - client_registration", code))? }
+        jack_on_info_shutdown(conn.handle, Some(info_shutdown_callback::<F>), user_ptr);
     }
+    Ok(())
 }

src/lib.rs

@@ -10,6 +10,9 @@ pub mod errors;
 pub mod handler;
 pub mod port;
 
+#[cfg(test)]
+mod tests;
+
 use jack_sys::*;
 use std::ffi::{CString, CStr};
 use std::marker::PhantomData;
@@ -23,7 +26,7 @@ bitflags! {
     /// Status of an operation.
     ///
     /// See `STATUS_*` constants for possible values.
-    pub flags JackStatus: libc::c_uint {
+    pub flags JackStatus: jack_status_t {
         /// Overall operation failed.
         const STATUS_FAILURE = jack_sys::JackFailure,
         /// The operation contained an invalid or unsupported option.

src/tests.rs

@@ -0,0 +1,112 @@
+//! Tests
+use *;
+use std::thread;
+use std::sync::atomic::AtomicBool;
+use std::sync::atomic::Ordering::*;
+use std::sync::Arc;
+
+#[test]
+fn panicking() {
+    let i_witnessed_a_panic = Arc::new(AtomicBool::new(false));
+    fn run(iwp: Arc<AtomicBool>) -> JackResult<()> {
+        let mut conn = JackConnection::connect("Testing", None)?;
+        let mut first = false;
+        conn.set_handler(move |_: &JackCallbackContext| {
+            if !first {
+                first = true;
+            }
+            else {
+                // uh-oh, JACK called us again after panicking!
+                iwp.store(true, Relaxed);
+            }
+            panic!("Hi, I'm a closure, and I'm a panic-a-holic.");
+        })?;
+        let _ = match conn.activate() {
+            Ok(nc) => nc,
+            Err((_, err)) => return Err(err)
+        };
+        thread::sleep(::std::time::Duration::new(2, 0));
+        Ok(())
+    }
+    run(i_witnessed_a_panic.clone()).unwrap();
+    assert_eq!(i_witnessed_a_panic.load(Relaxed), false);
+}
+#[test]
+fn thread_init() {
+    let atomic = Arc::new(AtomicBool::new(false));
+    struct Special(Arc<AtomicBool>);
+    impl JackHandler for Special {
+        fn thread_init(&mut self) {
+            self.0.store(true, Relaxed)
+        }
+    }
+    fn run(atomic: Arc<AtomicBool>) -> JackResult<()> {
+        let mut conn = JackConnection::connect("Testing", None)?;
+        let special = Special(atomic);
+        conn.set_handler(special)?;
+        let _ = match conn.activate() {
+            Ok(nc) => nc,
+            Err((_, err)) => return Err(err)
+        };
+        thread::sleep(::std::time::Duration::new(2, 0));
+        Ok(())
+    }
+    run(atomic.clone()).unwrap();
+    assert_eq!(atomic.load(Relaxed), true);
+}
+#[test]
+fn sawtooth() {
+    struct Sawtooth {
+        out1: JackPort,
+        out2: JackPort,
+        left_saw: f32,
+        right_saw: f32,
+        xrun: Arc<AtomicBool>
+    }
+    impl JackHandler for Sawtooth {
+        fn process(&mut self, ctx: &JackCallbackContext) -> JackControl {
+            let out1 = ctx.get_port_buffer(&self.out1).unwrap();
+            let out2 = ctx.get_port_buffer(&self.out2).unwrap();
+            for (out1, out2) in out1.iter_mut().zip(out2.iter_mut()) {
+                *out1 = self.left_saw * 0.1;
+                *out2 = self.right_saw * 0.1;
+                self.left_saw += 0.01;
+                if self.left_saw >= 1.0 { self.left_saw -= 2.0; }
+                self.right_saw += 0.03;
+                if self.right_saw >= 1.0 { self.right_saw -= 2.0; }
+            }
+            JackControl::Continue
+        }
+        fn xrun(&mut self) -> JackControl {
+            self.xrun.store(true, Relaxed);
+            JackControl::Continue
+        }
+    }
+    fn run(b: Arc<AtomicBool>) -> JackResult<()> {
+        let mut conn = JackConnection::connect("Very Annoying Sawtooth Generator", None)?;
+        let out1 = conn.register_port("output_1", PORT_IS_OUTPUT)?;
+        let out2 = conn.register_port("output_2", PORT_IS_OUTPUT)?;
+        let data = Sawtooth {
+            out1: out1,
+            out2: out2,
+            left_saw: 0.0,
+            right_saw: 0.0,
+            xrun: b
+        };
+        conn.set_handler(data)?;
+        let mut conn = match conn.activate() {
+            Ok(nc) => nc,
+            Err((_, err)) => return Err(err)
+        };
+        let ports = conn.get_ports(None, None, Some(PORT_IS_INPUT | PORT_IS_PHYSICAL))?;
+        if ports.len() >= 2 {
+            conn.connect_ports(&out1, &ports[0])?;
+            conn.connect_ports(&out2, &ports[1])?;
+        }
+        thread::sleep(::std::time::Duration::new(2, 0));
+        Ok(())
+    }
+    let atomic = Arc::new(AtomicBool::new(false));
+    run(atomic.clone()).unwrap();
+    assert_eq!(atomic.load(Relaxed), false);
+}