Struct ableton_link::Link

pub struct Link { /* fields omitted */ }

Represents a participant in a Link session.

Each Link instance has its own session state which represents a beat timeline and a transport start/stop state. The timeline starts running from beat 0 at the initial tempo when constructed. The timeline always advances at a speed defined by its current tempo, even if transport is stopped. Synchronizing to the transport start/stop state of Link is optional for every peer. The transport start/stop state is only shared with other peers when start/stop synchronization is enabled.

A Link instance is initially disabled after construction, which means that it will not communicate on the network. Once enabled, a Link instance initiates network communication in an effort to discover other peers. When peers are discovered, they immediately become part of a shared Link session.

Each method of the Link type documents its thread-safety and realtime-safety properties. When a method is marked thread-safe, it means it is safe to call from multiple threads concurrently. When a method is marked realtime-safe, it means that it does not block and is appropriate for use in the thread that performs audio IO.

Link provides one session state capture/commit method pair for use in the audio thread and one for all other application contexts. In general, modifying the session state should be done in the audio thread for the most accurate timing results. The ability to modify the session state from application threads should only be used in cases where an application's audio thread is not actively running or if it doesn't generate audio at all. Modifying the Link session state from both the audio thread and an application thread concurrently is not advised and will potentially lead to unexpected behavior.

Methods

impl Link

pub fn new(bpm: f64) -> Link

Construct with an initial tempo.

pub fn is_enabled(&self) -> bool

Is Link currently enabled?

• Thread-safe: yes
• Realtime-safe: yes

pub fn enable(&mut self, enable: bool)

Enable/disable Link.

• Thread-safe: yes
• Realtime-safe: no

pub fn is_start_stop_sync_enabled(&self) -> bool

Is start/stop synchronization enabled?

• Thread-safe: yes
• Realtime-safe: no

pub fn enable_start_stop_sync(&mut self, enable: bool)

Enable start/stop synchronization.

• Thread-safe: yes
• Realtime-safe: no

pub fn num_peers(&self) -> usize

How many peers are currently connected in a Link session?

• Thread-safe: yes
• Realtime-safe: yes

pub fn set_num_peers_callback(&mut self, callback: extern "C" fn(_: usize))

Register a callback to be notified when the number of peers in the Link session changes.

• Thread-safe: yes
• Realtime-safe: no

The callback is invoked on a Link-managed thread.

pub fn set_tempo_callback(&mut self, callback: extern "C" fn(_: f64))

Register a callback to be notified when the session tempo changes.

• Thread-safe: yes
• Realtime-safe: no

The callback is invoked on a Link-managed thread.

pub fn set_start_stop_callback(&mut self, callback: extern "C" fn(_: bool))

Register a callback to be notified when the state of start/stop isPlaying changes.

• Thread-safe: yes
• Realtime-safe: no

The callback is invoked on a Link-managed thread.

pub fn clock(&self) -> Clock

The clock used by Link.

• Thread-safe: yes
• Realtime-safe: yes

The Clock type is a platform-dependent representation of the system clock. It exposes a ticks() method that returns the current ticks of the system clock as well as micros(), which is a normalized representation of the current system time in std::chrono::microseconds. It also provides conversion functions ticksToMicros() and microsToTicks() to faciliate converting between these units.

pub fn with_audio_session_state<F>(&self, f: F) where
    F: FnMut(SessionState), 

Capture the current Link Session State from the audio thread.

• Thread-safe: no
• Realtime-safe: yes

This method should ONLY be called in the audio thread and must not be accessed from any other threads. The closure passes a snapshot of the current Link Session State, it should only be used in the local scope. Storing the Session State for later use in a different context is not advised because it will provide an outdated view.

pub fn commit_audio_session_state(&mut self, ss: SessionState)

Commit the given Session State to the Link session from the audio thread.

• Thread-safe: no
• Realtime-safe: yes

This method should ONLY be called in the audio thread. The given Session State will replace the current Link state. Modifications will be communicated to other peers in the session.

pub fn with_app_session_state<F>(&self, f: F) where
    F: FnMut(SessionState), 

Capture the current Link Session State from an application thread.

• Thread-safe: yes
• Realtime-safe: no

Provides a mechanism for capturing the Link Session State from an application thread (other than the audio thread). The closure passes a Session State that stores a snapshot of the current Link state, it should only be used in the local scope. Storing it for later use in a different context is not advised because it will provide an outdated view.

pub fn commit_app_session_state(&mut self, ss: SessionState)

Commit the given Session State to the Link session from an application thread.

• Thread-safe: yes
• Realtime-safe: no

The given Session State will replace the current Link Session State. Modifications of the Session State will be communicated to other peers in the session.

Trait Implementations

impl Drop for Link

fn drop(&mut self)

Executes the destructor for this type.