Struct AuxiliaryTask 

pub struct AuxiliaryTask { /* private fields */ }

A task that runs a callback on a lower-priority thread when the audio thread asks it to.

This is how a Bela program does work that must not happen in render: file and network I/O, expensive calculations that would overrun the block deadline, anything that allocates or blocks. render calls schedule, which is real-time safe, and the callback then runs on its own thread.

Ownership of the task’s state

The callback owns everything it touches: it is a 'static closure, moved into the task at creation. It cannot borrow from the application, because it runs on its own thread while the audio thread is inside render holding &mut self. Share state with render the way threads normally do — atomics, or a lock-free queue — and keep the real-time end of it allocation- and lock-free.

Lifetime

Create tasks in setup (creating one allocates and starts a thread, so render is the wrong place). They live until the audio system they were created in is torn down, which deletes all of them at once: the C API has no way to delete one task, so dropping this handle does not destroy the task, and the callback’s state stays allocated for the life of the process.

Because that teardown frees the tasks behind the handles, a handle records which audio system it belongs to, and scheduling it afterwards does nothing — including a handle that outlived one audio system while a later one is running, and including one from an audio system that was initialised but never started.

Tasks cannot be created during a teardown at all: from cleanup, or from another thread while an audio system is being dropped, new fails with Error::TaskCreateWhileStopping rather than handing back a task that is about to be deleted.

Shared, but only within a callback

The handle is Send and Sync, because an application is both and holds its tasks: with more than one render thread, every one of them reaches the same handle through &self. Scheduling from several at once is what libbela does itself — Bela_scheduleAuxiliaryTask takes the task’s mutex and notifies its condition variable, and a call that cannot take the lock reports the request as lost, which is already the documented behaviour below.

What keeps that from being a licence to schedule from anywhere is the context schedule asks for: a context cannot leave the callback it was handed to, so a handle sent to an unrelated thread still has nothing to schedule with.

Example

use core::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;

use bela::{
    AuxiliaryTask, BelaApplication, Priority, RenderContext, SetupContext, ThreadInfo,
    rt_println,
};

struct App {
    task: Option<AuxiliaryTask>,
    blocks: Arc<AtomicU64>,
}

impl BelaApplication for App {
    type RenderState = ();

    fn setup(&mut self, _context: &SetupContext) -> bool {
        let blocks = Arc::clone(&self.blocks);
        let priority = Priority::new(50).expect("50 is within Bela's priority range");
        self.task = AuxiliaryTask::new("report", priority, move || {
            rt_println!("{} blocks so far", blocks.load(Ordering::Relaxed));
        })
        .ok();
        self.task.is_some()
    }

    fn create_render_state(&mut self, _thread: ThreadInfo, _context: &SetupContext) {}

    fn render(&self, _state: &mut (), context: &mut RenderContext) {
        let blocks = self.blocks.fetch_add(1, Ordering::Relaxed) + 1;
        if blocks % 1000 == 0 {
            if let Some(task) = &self.task {
                task.schedule(context);
            }
        }
    }
}

Implementations

impl AuxiliaryTask

pub fn new<F>( name: &str, priority: Priority, callback: F, ) -> Result<Self, Error>

where F: FnMut() + Send + 'static,

Creates a task that runs callback each time it is scheduled.

name must be unique across the system (Bela names the underlying thread with it), and priority should stay below Priority::AUDIO. Bela permits the full range represented by Priority, including the audio thread’s own priority and priorities above it.

The callback runs on a real-time thread of its own, but one that is allowed to miss deadlines: it may allocate, block and make system calls. Doing so still costs the rest of the real-time system, so prefer to keep it modest.

A panic inside the callback crosses a C boundary; binaries should set panic = "abort" as the crate documentation recommends.

Errors

Returns Error::TaskName when name contains a NUL byte, Error::TaskCreateWhileStopping when an audio system is being torn down — including from a cleanup callback, which runs inside that teardown — and Error::TaskCreate when Bela could not create the task, which is also what happens off-device, where there is no audio system to create it in.

Examples found in repository

examples/task_lifecycle.rs (lines 52-54)

    fn setup(&mut self, _context: &SetupContext) -> bool {
        let runs = Arc::clone(&self.runs);
        match AuxiliaryTask::new("bela-rs-abandoned", TASK_PRIORITY, move || {
            runs.fetch_add(1, Ordering::Relaxed);
        }) {
            Ok(task) => {
                // Hand the handle out, as a Send handle could be handed
                // to any other thread.
                *self.handle.lock().unwrap_or_else(PoisonError::into_inner) = Some(task);
                true
            }
            Err(error) => {
                rt_println!("lifecycle: could not create the abandoned task: {error}");
                false
            }
        }
    }

    fn create_render_state(&mut self, _thread: ThreadInfo, _context: &SetupContext) {}

    fn render(&self, _state: &mut (), _context: &mut RenderContext) {}
}

/// Runs for real, scheduling both the stale handle and one of its own.
struct Survivor {
    stale: Option<AuxiliaryTask>,
    stale_runs: Arc<AtomicU64>,
    fresh: Option<AuxiliaryTask>,
    fresh_runs: Arc<AtomicU64>,
    blocks: u64,
    interval: u64,
}

impl BelaApplication for Survivor {
    type RenderState = ();

    fn setup(&mut self, context: &SetupContext) -> bool {
        #[allow(
            clippy::cast_possible_truncation,
            clippy::cast_sign_loss,
            reason = "the sample rate is a small positive number"
        )]
        let sample_rate_hz = context.audio_sample_rate() as u64;
        self.interval = (sample_rate_hz / context.audio_frames().max(1) as u64).max(1);

        let runs = Arc::clone(&self.fresh_runs);
        self.fresh = AuxiliaryTask::new("bela-rs-survivor", TASK_PRIORITY, move || {
            runs.fetch_add(1, Ordering::Relaxed);
        })
        .ok();
        self.fresh.is_some()
    }

    fn create_render_state(&mut self, _thread: ThreadInfo, _context: &SetupContext) {}

    fn render(&self, _state: &mut (), _context: &mut RenderContext) {}

    // Real-time safe: a counter and two schedules, both of which
    // return immediately. Once per block, on the main audio thread.
    fn render_post(&mut self, _states: &mut [()], context: &mut BlockContext) {
        self.blocks += 1;
        if self.blocks % self.interval != 0 {
            return;
        }
        if let Some(stale) = &self.stale {
            stale.schedule(context);
        }
        if let Some(fresh) = &self.fresh {
            fresh.schedule(context);
        }
    }

    fn cleanup(&mut self, _states: &mut [()], _context: &CleanupContext) {
        // `cleanup` runs inside the teardown, so this must fail.
        let created = AuxiliaryTask::new("bela-rs-in-cleanup", TASK_PRIORITY, || {});
        let cleanup_create = match created {
            Err(Error::TaskCreateWhileStopping) => "rejected",
            Err(_) => "failed-otherwise",
            Ok(_) => "created",
        };
        rt_println!(
            "lifecycle: stale-runs={} fresh-runs={} cleanup-create={}",
            self.stale_runs.load(Ordering::Relaxed),
            self.fresh_runs.load(Ordering::Relaxed),
            cleanup_create
        );
    }

examples/aux_task.rs (lines 85-92)

    fn setup(&mut self, context: &SetupContext) -> bool {
        #[allow(
            clippy::cast_possible_truncation,
            clippy::cast_sign_loss,
            reason = "the sample rate is a small positive number"
        )]
        let sample_rate_hz = context.audio_sample_rate() as u64;
        self.interval = (sample_rate_hz / context.audio_frames().max(1) as u64).max(1);

        // The callback owns everything it touches: it cannot borrow
        // from the application, which the audio thread is using while
        // the task runs.
        let blocks = Arc::clone(&self.blocks);
        let runs = Arc::clone(&self.runs);
        let task = AuxiliaryTask::new("bela-rs-report", TASK_PRIORITY, move || {
            runs.fetch_add(1, Ordering::Relaxed);
            let count = blocks.load(Ordering::Relaxed);
            // Allocating here is the point of the exercise: this is a
            // normal thread, so it may do what the audio thread may not.
            let bar = "#".repeat((count / 10_000) as usize + 1);
            rt_println!("task: {count} blocks {bar}");
        });

        match task {
            Ok(task) => {
                self.task = Some(task);
                rt_println!("setup: reporting every {} blocks", self.interval);
                true
            }
            Err(error) => {
                rt_println!("setup: could not create the task: {error}");
                false
            }
        }
    }

examples/cpu.rs (lines 141-145)

    fn setup(&mut self, context: &SetupContext) -> bool {
        let sample_rate = context.audio_sample_rate();
        for (index, increment) in self.phase_increments.iter_mut().enumerate() {
            #[allow(
                clippy::cast_precision_loss,
                reason = "the oscillator index is far below f32's exact integer range"
            )]
            let harmonic = index as f32 + 1.0;
            *increment = TAU * BASE_FREQUENCY * harmonic / sample_rate;
        }

        #[allow(
            clippy::cast_possible_truncation,
            clippy::cast_sign_loss,
            reason = "the sample rate is a small positive number"
        )]
        let sample_rate_hz = sample_rate as u64;
        self.blocks_per_report = (sample_rate_hz / context.audio_frames().max(1) as u64).max(1);

        if context.cpu_usage().is_none() {
            rt_println!("setup: CPU monitoring is off; run with Settings::cpu_monitoring");
            return false;
        }

        // The callback owns everything it touches: the percentages
        // arrive through the atomics, because the audio thread's
        // counters cannot be read from this thread.
        let published = Arc::clone(&self.published);
        let task = AuxiliaryTask::new("bela-rs-cpu", TASK_PRIORITY, move || {
            let thread = f32::from_bits(published.thread.load(Ordering::Relaxed));
            let section = f32::from_bits(published.section.load(Ordering::Relaxed));
            rt_println!("cpu: audio thread {thread:.1}%; oscillators {section:.1}%");
        });

        match task {
            Ok(task) => {
                self.task = Some(task);
                rt_println!(
                    "setup: {OSCILLATORS} oscillators over {} render thread(s), \
                     reporting every {} blocks",
                    context.thread_count(),
                    self.blocks_per_report
                );
                true
            }
            Err(error) => {
                rt_println!("setup: could not create the task: {error}");
                false
            }
        }
    }

pub fn schedule(&self, _context: &impl CallbackContext)

Asks for the callback to run.

Real-time safe: this is the call render makes. It returns immediately, without waiting for the callback.

Why it takes a context

The context is a witness that this is a Bela callback — any of them — which is the only place scheduling is sound. Stopping the audio system frees every task, and Bela_stopAudio joins the main audio thread and then every render thread before it does so, so a schedule made from a callback can never be in flight while the task behind it is freed. A handle sent to some other thread (the type is Send, since applications are) has no context to schedule with, and so cannot race with that teardown.

Requests can be lost

A request that arrives while the callback is still running is dropped, not queued, and nothing reports it: Bela wakes a condition variable the task is not waiting on, and its return value only says whether that wakeup could be delivered. Measured on the board, a task sleeping 2 ms scheduled from every block ran 1507 times for 9052 requests, with every request reported as successful.

So do not treat one schedule as one run. When it matters, have the callback count its own invocations and compare that with the number of requests.

Once the audio system this task belongs to has stopped, every task is gone and this does nothing — cleanup runs after that point.

First schedule of a task

libbela forces a task’s thread to start the first time the task is scheduled, by raising and restoring its priority. Two render threads doing that at the same time can make libbela print Force starting scheduled thread didn't work on standard error; nothing else comes of it, and the next schedule finds the thread started. Scheduling a task once from setup or render_pre before the render threads share it avoids the message.

Examples found in repository

examples/aux_task.rs (line 119)

    fn render_post(&mut self, _states: &mut [()], context: &mut BlockContext) {
        let blocks = self.blocks.fetch_add(1, Ordering::Relaxed) + 1;
        if blocks % self.interval != 0 {
            return;
        }
        if let Some(task) = &self.task {
            task.schedule(context);
            self.requests += 1;
        }
    }

examples/task_lifecycle.rs (line 115)

    fn render_post(&mut self, _states: &mut [()], context: &mut BlockContext) {
        self.blocks += 1;
        if self.blocks % self.interval != 0 {
            return;
        }
        if let Some(stale) = &self.stale {
            stale.schedule(context);
        }
        if let Some(fresh) = &self.fresh {
            fresh.schedule(context);
        }
    }

examples/cpu.rs (line 248)

    fn render_post(&mut self, states: &mut [Bank], context: &mut BlockContext) {
        #[allow(
            clippy::cast_precision_loss,
            reason = "a block's frame count is far below f32's exact integer range"
        )]
        let frames = context.audio_frames() as f32;
        for (phase, increment) in self.phases.iter_mut().zip(&self.phase_increments) {
            *phase = (*phase + frames * increment) % TAU;
        }

        self.blocks += 1;
        if self.blocks % self.blocks_per_report != 0 {
            return;
        }
        // Read here, on the main audio thread, and handed to the task
        // as plain numbers.
        let thread = context.cpu_usage().map_or(0.0, |usage| usage.percentage());
        let section = states
            .first()
            .map_or(0.0, |bank| bank.timer.usage().percentage());
        self.published
            .thread
            .store(thread.to_bits(), Ordering::Relaxed);
        self.published
            .section
            .store(section.to_bits(), Ordering::Relaxed);
        if let Some(task) = &self.task {
            task.schedule(context);
        }
    }

Trait Implementations

impl Debug for AuxiliaryTask

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Send for AuxiliaryTask

impl Sync for AuxiliaryTask