Docs file normalization.
This commit is contained in:
parent
dd32143bf8
commit
619c2d0808
46 changed files with 3587 additions and 2579 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue