refactor(engine): flatten

- add `just stats`
- add basic doctests

engine/jack_traits.rs

@@ -0,0 +1,104 @@
+use crate::*;
+
+/// Things that can provide a [jack::Client] reference.
+///
+/// ```
+/// #[derive(Default)] struct Jacked<'j>(tek_engine::Jack<'j>);
+///
+/// impl tek_engine::HasJack<'j> for Jacked<'j> {
+///     fn jack (&self) -> &Jack<'j> { &self.0 }
+/// }
+///
+/// let jack: &Jack<'j> = Jacked::default().jack();
+/// ```
+pub trait HasJack<'j>: Send + Sync {
+
+    /// Return the internal [jack::Client] handle
+    /// that lets you call the JACK API.
+    fn jack (&self) -> &Jack<'j>;
+
+    fn with_client <T> (&self, op: impl FnOnce(&Client)->T) -> T {
+        self.jack().with_client(op)
+    }
+
+    fn port_by_name (&self, name: &str) -> Option<Port<Unowned>> {
+        self.with_client(|client|client.port_by_name(name))
+    }
+
+    fn port_by_id (&self, id: u32) -> Option<Port<Unowned>> {
+        self.with_client(|c|c.port_by_id(id))
+    }
+
+    fn register_port <PS: PortSpec + Default> (&self, name: impl AsRef<str>) -> Usually<Port<PS>> {
+        self.with_client(|client|Ok(client.register_port(name.as_ref(), PS::default())?))
+    }
+
+    fn sync_lead (&self, enable: bool, callback: impl Fn(TimebaseInfo)->Position) -> Usually<()> {
+        if enable {
+            self.with_client(|client|match client.register_timebase_callback(false, callback) {
+               Ok(_) => Ok(()),
+                Err(e) => Err(e)
+            })?
+        }
+        Ok(())
+    }
+
+    fn sync_follow (&self, _enable: bool) -> Usually<()> {
+        // TODO: sync follow
+        Ok(())
+    }
+}
+
+/// Trait for thing that has a JACK process callback.
+pub trait Audio {
+
+    /// Handle a JACK event.
+    fn handle (&mut self, _event: JackEvent) {}
+
+    /// Projecss a JACK chunk.
+    fn process (&mut self, _: &Client, _: &ProcessScope) -> Control {
+        Control::Continue
+    }
+
+    /// The JACK process callback function passed to the server.
+    fn callback (
+        state: &Arc<RwLock<Self>>, client: &Client, scope: &ProcessScope
+    ) -> Control where Self: Sized {
+        if let Ok(mut state) = state.write() {
+            state.process(client, scope)
+        } else {
+            Control::Quit
+        }
+    }
+
+}
+
+/// Implement [Audio]: provide JACK callbacks.
+#[macro_export] macro_rules! audio {
+
+    (|
+        $self1:ident:
+        $Struct:ident$(<$($L:lifetime),*$($T:ident$(:$U:path)?),*>)?,$c:ident,$s:ident
+    |$cb:expr$(;|$self2:ident,$e:ident|$cb2:expr)?) => {
+        impl $(<$($L),*$($T $(: $U)?),*>)? Audio for $Struct $(<$($L),*$($T),*>)? {
+            #[inline] fn process (&mut $self1, $c: &Client, $s: &ProcessScope) -> Control { $cb }
+            $(#[inline] fn handle (&mut $self2, $e: JackEvent) { $cb2 })?
+        }
+    };
+
+    ($Struct:ident: $process:ident, $handle:ident) => {
+        impl Audio for $Struct {
+            #[inline] fn process (&mut self, c: &Client, s: &ProcessScope) -> Control {
+                $process(self, c, s)
+            }
+            #[inline] fn handle (&mut self, e: JackEvent) {
+                $handle(self, e)
+            }
+        }
+    };
+
+}
+
+pub trait JackPerfModel {
+    fn update_from_jack_scope (&self, t0: Option<u64>, scope: &ProcessScope);
+}