Docs file normalization.

This commit is contained in:
Johannes Findeisen 2026-11-06 15:20:20 +01:00
commit 619c2d0808
46 changed files with 3587 additions and 2579 deletions

View file

@ -1,7 +1,9 @@
# Decision 0004: JACK backend and bounded plan handoff
# Decision 0004: JACK Backend and Bounded Plan Handoff
**Status:** Accepted
---
## Backend
Use the JACK C client API. The inspected system provides PipeWire's maintained
@ -22,10 +24,12 @@ framework or second driver implementation.
The optional dependency provides actual audio callbacks and port routing.
PipeWire's installed JACK library is MIT licensed (`pipewire-jack/COPYING`).
Traditional JACK client libraries use LGPL licensing; review the actual linked
implementation, transitive libraries and notices when distributing. Nothing
is bundled or installed here. ALSA is still a future MIDI candidate.
implementation, transitive libraries and notices when distributing. Nothing is
bundled or installed here. ALSA is still a future MIDI candidate.
## C99 and atomic operations
---
## C99 and Atomic Operations
Retain C99 and use GCC/Clang `__atomic` builtins. This is a documented compiler
extension, avoiding a language-standard change and keeping the existing core
@ -34,12 +38,15 @@ unsigned-int atomics to be always lock-free, or returns unsupported before
callbacks are installed. Naturally aligned fields reside in calloc-allocated
objects. There is no mutex or libatomic fallback in the callback path.
## Ownership and publication
---
## Ownership and Publication
One serialized control producer and one audio consumer share two pointer slots:
- `pending`: producer publishes a fully compiled plan with release; consumer
exchanges it for NULL with acquire/release at the next eligible block boundary.
exchanges it for NULL with acquire/release at the next eligible block
boundary.
- `retired`: consumer releases its previous active plan into this slot only
after its final access. Producer exchanges with NULL using acquire/release,
then destroys that acknowledged plan on the control thread.
@ -50,40 +57,47 @@ callers never receive plan pointers through the realtime/backend API.
A full pending slot returns capacity without replacing anything. A full retired
slot defers adoption while the current plan continues processing. The consumer
performs at most one adoption per block and never loops waiting for the producer.
Producer collection can overlap processing because the retired plan is no
longer reachable from the consumer. Collection clears the slot before freeing;
consumer may then retire another, distinct plan. Publication never immediately
frees the previously active plan.
performs at most one adoption per block and never loops waiting for the
producer. Producer collection can overlap processing because the retired plan is
no longer reachable from the consumer. Collection clears the slot before
freeing; consumer may then retire another, distinct plan. Publication never
immediately frees the previously active plan.
Submitting collects any already retired plan, so a producer repeatedly submitting
also reclaims memory. If it becomes idle, one pending, one active, and one retired
plan bound retained resources (at most three plans, each with up to 64 MiB of
sample buffers). Periodic collect is recommended. Shutdown closes the JACK client
and synchronizes its callbacks before destroying any active/pending/retired plan.
Standalone realtime-engine callers must stop and join their consumer themselves.
Submitting collects any already retired plan, so a producer repeatedly
submitting also reclaims memory. If it becomes idle, one pending, one active,
and one retired plan bound retained resources (at most three plans, each with up
to 64 MiB of sample buffers). Periodic collect is recommended. Shutdown closes
the JACK client and synchronizes its callbacks before destroying any
active/pending/retired plan. Standalone realtime-engine callers must stop and
join their consumer themselves.
## Status, errors and recovery
---
Unsigned-int status fields use lock-free atomics. Values are individual snapshots,
not one transactional state. Counters wrap naturally; no string formatting,
logging, allocation, GUI operation or blocking synchronization occurs in project
callbacks. JACK's shutdown notification only stores a flag and leaves cleanup to
the control thread. Other notifications store the current format and xrun count.
## Status, Errors and Recovery
Unsigned-int status fields use lock-free atomics. Values are individual
snapshots, not one transactional state. Counters wrap naturally; no string
formatting, logging, allocation, GUI operation or blocking synchronization
occurs in project callbacks. JACK's shutdown notification only stores a flag and
leaves cleanup to the control thread. Other notifications store the current
format and xrun count.
Buffer changes within the configured maximum require no allocation. Larger
blocks are fully silenced and reported as capacity errors; smaller blocks can
resume processing. Sample-rate changes latch a flag and silence processing
rather than replaying an oscillator compiled for a different rate. Close/reopen
and resubmit after a rate change or server loss. There is no automatic reconnect.
JACK-deactivate pauses the retained plan; restart continues its oscillator phase.
Plan replacement starts the newly compiled oscillator at phase zero, without
crossfade. Smooth parameter ramps and click-free graph transitions are future work.
and resubmit after a rate change or server loss. There is no automatic
reconnect. JACK-deactivate pauses the retained plan; restart continues its
oscillator phase. Plan replacement starts the newly compiled oscillator at phase
zero, without crossfade. Smooth parameter ramps and click-free graph transitions
are future work.
No stereo, recording, MIDI, native PipeWire API, GUI engine controls or hardware
configuration dialogs are included.
## Adoption acknowledgement and stopped editing
---
## Adoption Acknowledgement and Stopped Editing
The pending pointer has an associated atomic revision. Producer stores the
revision before release-publishing the pointer. Consumer acquire-loads a
@ -97,10 +111,10 @@ snapshots, not plan pointers or a multi-field transactional snapshot.
While JACK is stopped, a backend submission builds a separate realtime engine,
submits/compiles the graph there, and replaces the retained engine only on
success. Process callbacks cannot run on an inactive client or after successful
deactivation, and notification callbacks do not access the engine pointer.
The control thread can therefore reclaim all old state safely. Counters and
oscillator phases restart for that new engine epoch. The standalone realtime
API keeps its one-pending-slot contract regardless of external stop state.
deactivation, and notification callbacks do not access the engine pointer. The
control thread can therefore reclaim all old state safely. Counters and
oscillator phases restart for that new engine epoch. The standalone realtime API
keeps its one-pending-slot contract regardless of external stop state.
The callback still adopts at most one plan and never allocates/frees. Revision
ordering is tested alongside the plan's rendered gain under 2,000 concurrent