Skip to content

Sync development/v2 into main (history only; no file changes) - #34

Merged
tap merged 16 commits into
mainfrom
development/v2
Oct 1, 2026
Merged

tap merged 16 commits into
mainfrom
development/v2

Conversation

@tap

@tap tap commented Oct 1, 2026

Copy link
Copy Markdown
Owner

The second half of syncing the two branches after 0.10.0. I've already merged main into development/v2 (cbf0cc4); this PR brings development/v2 back into main.

No files change: the trees are identical. 0.10.0 reached main as development/v2's commits replayed onto main, so the same changes exist on both branches with different commit IDs. Merging this, as a merge commit, makes development/v2's own history part of main's. After that, development/v2 and main agree, and future work can branch from either.

One thing worth knowing about the merge into development/v2: git combined the two CHANGELOGs "cleanly" but wrongly. It kept development/v2's sections where "Unreleased" used to be and main's copy under 0.10.0, so every new section appeared twice, the second copy under 0.9.0. I took main's CHANGELOG to fix it, and checked the result is byte-for-byte main's tree before pushing.

🤖 Generated with Claude Code

https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz

tap and others added 16 commits September 30, 2026 10:22
…ecksums

- run.py --package tests a package installed in Packages (a release zip,
  unzipped) instead of this checkout: its external, runtime and python/.
  The v0.9.0 Intel zip, so installed, passes the whole suite (plan 6.5).
- run.py no longer waits for Max's file database: tests are opened by name
  through the search path, which does not need it, and with a release
  installed it took minutes to report ready.
- A session that fails before its first test reports its tests as never
  run, instead of every result the harness has ever recorded.
- release.yml attaches each zip's .sha256, as the ReadMe says, and builds
  SHA256SUMS from the zips (joining the .sha256 files depended on each
  ending in a newline; the Windows one does not).
- The plan records 6.5's progress and what the release check found.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz
…(2.6)

Measured first: core/bench/reload_bench.cpp runs an audio thread with Core
Audio's real-time scheduling, computing 512-sample buffers of 64-sample
vectors at 96 kHz, while the main thread saves and reloads the class every
100 ms. A reload of the allpass examples holds the GIL for about 3.5 ms, and
with CPython's 5 ms switch interval the audio thread waited for all of it:
late buffers in most runs, the worst 45 ms (the reloading thread
descheduled while holding the GIL).

The runtime now sets a 0.5 ms switch interval (runtime_options::
switch_interval): across three runs no buffer was late, the 99th percentile
fell to 0.7–2 ms, and the median was unchanged. 0.2 ms did as well; 0.1 ms
did worse. Splitting load() into phases was not needed for files this size
— what a switch cannot interrupt is a single C call, compiling the file
above all, which is short for them.

A core test pins the setting; the tests that briefly set 1 µs now restore
whatever was set rather than CPython's 5 ms.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz
….10)

A file that fails to load was not cached, so every object sharing it ran it
and printed the traceback: 25 objects, 25 tracebacks. 6.7 left this alone
because remembering the failing source and staying quiet would also hide
the error from an object created later.

The loader still runs the file on every load (something it imports may
have been fixed), but marks a failure of the same source it reported less
than two seconds ago; the processor stays quiet for a marked failure. A
save, or a patch opening many objects, reports once; an object made later
reports again. compile() now sits inside the handler too, so a syntax
error is covered.

Pinned by a core test (two processors; another broken save; a later
object — it fails without the change) and by the runtime test
announce-once: a broken save with five objects in Max, one report (five
with the previous external). run.py now refuses an external older than
its sources, the mistake that first made this test fail.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz
processor::process() now takes N input and M output channels. The positional
parameters of the class's process() are its signal inputs — all np.ndarray
(once per vector) or all per sample; none makes a generator, whose return
hint then picks the path — and its return hint names the outputs: one value,
or tuple[...] of n. describe() now reports a tuple return's length and
element kind. input_count() and output_count() tell the host.

The host's channels are matched to the class's: an input the host does not
give reads as silence, an extra host output is silent, an extra class output
is dropped; channels may alias. Per sample, the arguments are a stack array
(capped at 64 channels): a shared scratch buffer could be resized by a
reload mid-vector. Per vector, each input has its own reused array; the set
is rebuilt swap-safely and never shrinks, so a process() still running on a
binding with more inputs finds enough. A result of the wrong length is
silenced and reported once per load; *args, mixed hints and a tuple of
unsaid length are reported and not bound.

The external passes every channel Max gives; until 2.4 (b) that is still
one and one. test_channels.cpp covers 2x2 per sample and per vector, a
generator, fewer and more host channels, in place, the errors, and the
counts across a reload and a failed one; the two-input and tuple fixtures
now test the new behaviour. No measurable cost for single-channel classes
(best of six alternating rounds against the old core: within 5%, both ways).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz
The constructor, after the first load, adds an inlet<> for each input the
class's process() declares after the first — its help naming the parameter
(processor::input_names()) — and an outlet<> for each output after the
first, before min makes the Max ports from its lists. After a reload that
changes the counts it says so, once, and the core matches the channels (a
missing input reads as silence, an extra output is dropped) until the
object is re-created; 2.4 (c) will adapt it in place instead.

New example stereo_width.py: two inputs and two outputs (left, right) and a
width attribute, per vector; tested in the core battery.

The mock test makes [tap.python~ stereo_width] and checks two inlets and
two outlets, both processed. For that the test file stands in a faithful
attr_args_offset (the mock's says 0: no argument ever reached an object),
and the object reads a one-symbol argument directly rather than through
atom_gettext (the mock's gives an empty string). The runtime test
"channels" checks it in Max: stereo_width at two widths, a generator with
no inputs taking a message, and a save that changes the shape.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz
…nlets and outlets in place

After a reload that changes how many inputs or outputs process() declares, the object finds its
box and, between dynlet_begin and dynlet_end, sets its signal inlets with dsp_resize and deletes or
appends outlets at the end, keeping the patch cords of those that stay; min's inlet and outlet
lists follow at once (with the inlets' help renamed on every reload), and the signal chain is
marked broken so it is rebuilt with the new counts. An object without a box keeps its ports and
says so, as before.

Mock test: the dynlet calls recorded against a pretend box, for saves that grow, shrink, rename
and break the class. Runtime test channels: grown from two to three, the old cords carry on and
cords connected to the new inlet and outlet carry signal (fails against the previous external);
shrunk to one, the removed outlets' cords go with them.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz
…e package for every platform)

The external's bundle identifier shipped as max-sdk-base's unexpanded Xcode template,
com.74objects.${PRODUCT_NAME:rfc1034identifier}: only Xcode expands it. The object's CMakeLists
now expands it from the project name with the same rule — com.74objects.tap.python-tilde — and
the macOS CI job checks it. assemble-package.py leaves docs/PRODUCTION-PLAN.md out of the package
(docs/ still ships, for the reference page Max reads).

The plan records the uv discussion as 4.7 and the decision to attach one all-platform package to
every tag, v0.x published as pre-releases automatically, as 4.8.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz
min rewrites docs/tap.python~.maxref.xml when Max loads an external newer than the page, and dates the external by its .mxo folder, which a rebuild leaves alone; the macOS build now touches the folder after each link. run.py says when Max has rewritten the page, the page Max wrote is committed, and the plan (6.8) and CLAUDE.md are updated.
….9) (#27)

The examples note suggests numpy_allpass beside allpass, with the patcher's CPU meter to compare them; a new note says process()'s parameters are the object's signal inlets and its return hint gives the outlets (stereo_width has two of each), and that a save which changes them changes the object. The plan's 6.9 is ticked.
Python on a thread of its own, a fixed latency of whole vectors behind the audio thread, which never takes the GIL: a lock-free ring of slots in the core, the existing processor::process() run on the worker, underruns output as silence with the latency kept, @mode and @Latency applied at the next chain compile, and the read-only @latencysamples reporting the latency in samples.
)

worker.h runs a processor's process() on a worker thread a fixed number of vectors behind the audio thread, which only copies vectors through a lock-free ring and never takes the GIL. A vector whose outputs are not ready in time is output as silence; the worker still processes it and catches up, so the latency stays fixed and the class sees every vector in order. A worker a whole ring behind drops new inputs until it catches up. Both are reported once per load from the main thread (the processor gains load_count() for that). The audio thread borrows the ring by taking an atomic pointer, so start() and stop() can run while a host's old signal chain still does.

Core battery: the output is the direct output L vectors later, per sample and per vector; channel matching; underruns, drops and their reports; restart and stop; reloads under an audio thread. Clean under ThreadSanitizer.
…ples

@mode worker runs process() on the core's worker, @Latency milliseconds behind the audio (30 by
default, rounded up to whole signal vectors); the read-only @latencysamples gives the delay in
samples, 0 in direct mode. Both settings take effect at once, by rebuilding the signal chain, and
the worker is started for each chain in dspsetup with the object's inlets and outlets.

What measuring in Max changed:
- The worker thread gets the scheduling of an audio thread — Mach's time-constraint policy on
  macOS, THREAD_PRIORITY_TIME_CRITICAL on Windows — through a hook the core calls on the thread as
  it starts: on a busy machine an ordinary thread was late even with 21 ms of latency. The core
  also makes the thread's Python thread state before the audio thread can give it work.
- Max computes an I/O vector's worth of signal vectors back to back (here 512 samples: 8 at once),
  so the worker has only the latency beyond that burst: 2 vectors (the first default) left a late
  vector in every second, 10 ms in 2 of 11. @Latency is therefore milliseconds, the whole delay,
  default 30, documented as having to exceed the I/O vector.

Fields are now checked against the host's reserved names as methods are, and the object reserves
its new attributes. @latencysamples is set directly (Max refuses to set a readonly attribute
through its own setter, which the mock kernel does not model). The runner's stale-build check
ignores the mock test's source.

Mock test: worker mode delays by @Latency, reports @latencysamples, and returns to direct mode.
Runtime test in Max (worker, at the default): the output matches delay~ by @latencysamples sample
for sample, through a 0.2 s stall (reported once) and a reload; @mode direct takes the delay away.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz
…would not

Measured with uv 0.12.21: its hash-pinned lock lists every distribution of each pin (68 hashes
against the 8 wheels update-locks.py pins), so the lock generator stays; 4.8 can merge the
platform builds CI already makes; the scripts need nothing but the standard library; and uv's
own Python is marked externally managed and newer than our pin, so the runtime stays ours. What
it is good for is now in the ReadMe and CLAUDE.md: `uv python install 3.13` for the Linux loop's
CPython with headers, and `uv pip install --python support/bin/python3` for adding packages to
the runtime.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz
A tag now also attaches PythonTap-<version>.zip, holding the macOS and Windows externals and each
platform's runtime in support/<platform>. The external uses support/<platform> when its package
has one and support/ otherwise (runtime_home()), so per-platform packages and checkouts work as
before; the universal macOS external carries an rpath per slice to support/macos-<arch>/lib ahead
of support/lib; Windows already loaded the DLL by full path from the runtime folder.

assemble-package.py --merge takes the three release zips, unzips them itself (backslash entry
names as folders, the macOS runtime's symlinks and executable bits kept), copies what must be the
same in all of them once (line endings aside), and puts each runtime in support/<platform> and
each platform's licenses in licenses/<platform>. release.yml's new all-platforms job runs it, and
the release job attaches the result, publishing 0.x tags as pre-releases (drafts from 1.0).

Checked in Max: a merged package with the Intel runtime as support/macos-x86_64, installed in
Packages, passes the whole runtime suite. Mock test: the runtime folder chosen.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz
main has 0.10.0: development/v2's work replayed onto main, and the changelog's release headings.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz
@tap
tap merged commit 41c1ae0 into main Oct 1, 2026
18 checks passed
@tap
tap deleted the development/v2 branch October 1, 2026 13:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant