Add support for slow-sync clients

Author: mgeier

examples/slow_sync.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Show how slow-sync clients work."""
+import time
+
+import jack
+
+slow = jack.Client('Slow')
+
+slow.pos = 0
+slow.ready_at = None
+slow.seek_time = 0.1
+
+
+@slow.set_sync_callback
+def slow_sync_callback(state, pos):
+    now = time.time()
+    print(jack.TransportState(state), pos.frame, end=' ')
+    if state == jack.STOPPED:
+        if slow.pos == pos.frame:
+            print('ready')
+            return True
+        if slow.ready_at is None:
+            slow.ready_at = now + slow.seek_time
+        if slow.ready_at < now:
+            print('just got ready')
+            slow.pos = pos.frame
+            slow.ready_at = None
+            return True
+        print('will be ready in {:.2f} seconds'.format(slow.ready_at - now))
+    elif state == jack.STARTING:
+        if slow.pos == pos.frame:
+            print('ready')
+            return True
+        if slow.ready_at is None:
+            slow.ready_at = now + slow.seek_time
+        if slow.ready_at < now:
+            print('just got ready')
+            slow.pos = pos.frame
+            slow.ready_at = None
+            return True
+        print('will be ready in {:.2f} seconds'.format(slow.ready_at - now))
+        return False
+    elif state == jack.ROLLING:
+        assert slow.pos != pos.frame
+        assert slow.ready_at is not None
+        if slow.ready_at < now:
+            print('just caught up')
+            slow.pos = pos.frame
+            slow.ready_at = None
+            return True
+        print('will catch up in {:.2f} seconds'.format(slow.ready_at - now))
+        return False
+    else:
+        assert False
+    return False
+
+
+# Make sure transport is stopped and at 0 initially
+slow.transport_stop()
+slow.transport_frame = 0
+
+print('== setting custom sync timeout')
+slow.set_sync_timeout(int(0.5 * slow.seek_time * 1000 * 1000))
+
+with slow:
+    time.sleep(0.1)  # Time to show STOPPED
+    print('== starting transport')
+    slow.transport_start()
+    time.sleep(0.1)  # Time to show STARTING
+    print('== stopping transport')
+    slow.transport_stop()
+    print('== seeking to 123')
+    slow.transport_frame = 123
+    time.sleep(0.5 * slow.seek_time)
+    print('== starting transport')
+    slow.transport_start()
+    time.sleep(slow.seek_time)
+    print('== stopping transport')
+    slow.transport_stop()
+    print('== setting default sync timeout')
+    slow.set_sync_timeout(2 * 1000 * 1000)
+    print('== seeking to 123')
+    slow.transport_frame = 123
+    time.sleep(0.5 * slow.seek_time)
+    print('== starting transport')
+    slow.transport_start()
+    time.sleep(slow.seek_time)
+    slow.transport_stop()

jack_build.py

@@ -79,6 +79,7 @@
 /* _jack_position: see below in "packed" section */
 typedef struct _jack_position jack_position_t;
 typedef void (*JackTimebaseCallback)(jack_transport_state_t state, jack_nframes_t nframes, jack_position_t *pos, int new_pos, void *arg);
+typedef int (*JackSyncCallback)(jack_transport_state_t state, jack_position_t *pos, void *arg);
 /* deprecated: jack_transport_bits_t */
 /* deprecated: jack_transport_info_t */
 
@@ -208,8 +209,8 @@
 /* transport.h */
 
 /* TODO: jack_release_timebase */
-/* TODO: jack_set_sync_callback */
-/* TODO: jack_set_sync_timeout */
+int jack_set_sync_callback(jack_client_t* client, JackSyncCallback sync_callback, void* arg);
+int jack_set_sync_timeout(jack_client_t* client, jack_time_t timeout);
 int jack_set_timebase_callback(jack_client_t* client, int conditional, JackTimebaseCallback timebase_callback, void* arg);
 int jack_transport_locate(jack_client_t* client, jack_nframes_t frame);
 jack_transport_state_t jack_transport_query(const jack_client_t* client, jack_position_t* pos);

src/jack.py

@@ -540,11 +540,9 @@ def transport_reposition_struct(self, position):
         effect in two process cycles.  If there are slow-sync clients
         and the transport is already rolling, it will enter the
         `STARTING` state and begin invoking their sync callbacks
-        (see `jack_set_sync_callback()`__) until ready.
+        (see `set_sync_callback()`) until ready.
         This function is realtime-safe.
 
-        __ http://jackaudio.org/files/docs/html/group__TransportControl.html
-
         Parameters
         ----------
         position : jack_position_t
@@ -559,6 +557,29 @@ def transport_reposition_struct(self, position):
         _check(_lib.jack_transport_reposition(self._ptr, position),
                'Error re-positioning transport')
 
+    def set_sync_timeout(self, timeout):
+        """Set the timeout value for slow-sync clients.
+
+        This timeout prevents unresponsive slow-sync clients from
+        completely halting the transport mechanism.  The default is two
+        seconds.  When the timeout expires, the transport starts
+        rolling, even if some slow-sync clients are still unready.
+        The *sync callbacks* of these clients continue being invoked,
+        giving them a chance to catch up.
+
+        Parameters
+        ----------
+        timeout : int
+            Delay (in microseconds) before the timeout expires.
+
+        See Also
+        --------
+        set_sync_callback
+
+        """
+        _check(_lib.jack_set_sync_timeout(self._ptr, timeout),
+               'Error setting sync timeout')
+
     def set_freewheel(self, onoff):
         """Start/Stop JACK's "freewheel" mode.
 
@@ -1175,6 +1196,67 @@ def callback_wrapper(_):
             self._ptr, callback_wrapper, _ffi.NULL),
             'Error setting xrun callback')
 
+    def set_sync_callback(self, callback):
+        """Register (or unregister) as a slow-sync client.
+
+        A slow-sync client is one that cannot respond immediately to
+        transport position changes.
+
+        The *callback* will be invoked at the first available
+        opportunity after its registration is complete.  If the client
+        is currently active this will be the following process cycle,
+        otherwise it will be the first cycle after calling `activate()`.
+        After that, it runs whenever some client requests a new
+        position, or the transport enters the `STARTING` state.
+        While the client is active, this callback is invoked just before
+        the *process callback* (see `set_process_callback()`) in the
+        same thread.
+
+        Clients that don't set a *sync callback* are assumed to be ready
+        immediately any time the transport wants to start.
+
+        Parameters
+        ----------
+        callback : callable or None
+
+            User-supplied function that returns ``True`` when the
+            slow-sync client is ready.  This realtime function must not
+            wait.  It must have this signature::
+
+                callback(state: int, pos: jack_position_t) -> bool
+
+            The *state* argument will be:
+
+            - `STOPPED` when a new position is requested;
+            - `STARTING` when the transport is waiting to start;
+            - `ROLLING` when the timeout has expired, and the position
+              is now a moving target.
+
+            The *pos* argument holds the new transport position using
+            the same structure as returned by
+            `transport_query_struct()`.
+
+            Setting *callback* to ``None`` declares that this
+            client no longer requires slow-sync processing.
+
+        See Also
+        --------
+        set_sync_timeout
+
+        """
+        if callback is None:
+            callback_wrapper = _ffi.NULL
+        else:
+
+            @self._callback('JackSyncCallback', error=False)
+            def callback_wrapper(state, pos, _):
+                return callback(state, pos)
+
+        _check(
+            _lib.jack_set_sync_callback(
+                self._ptr, callback_wrapper, _ffi.NULL),
+            'Error setting sync callback')
+
     def set_timebase_callback(self, callback=None, conditional=False):
         """Register as timebase master for the JACK subsystem.