From 28674a7c0e8b03779cd36b1ae9d333bab59c9b33 Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Wed, 30 Sep 2026 08:09:50 -0500 Subject: [PATCH 01/15] Check an installed release with the runtime tests; fix the release checksums - 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) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- .github/workflows/release.yml | 8 +++-- docs/PRODUCTION-PLAN.md | 21 +++++++++++-- runtime-tests/README.md | 5 +++ runtime-tests/run.py | 57 ++++++++++++++++++++++++++--------- 4 files changed, 72 insertions(+), 19 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index a219792..72bf9e3 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -210,13 +210,15 @@ jobs: - name: Checksums run: | cd dist - cat *.sha256 > SHA256SUMS - sha256sum -c SHA256SUMS + # from the zips themselves (joining the .sha256 files depended on each ending in a newline; + # Windows' does not), then each build's own .sha256 checked against them + sha256sum *.zip > SHA256SUMS + for f in *.zip.sha256; do sha256sum -c "$f"; done - name: Create the draft release env: GH_TOKEN: ${{ github.token }} run: | - gh release create "$GITHUB_REF_NAME" dist/*.zip dist/SHA256SUMS \ + gh release create "$GITHUB_REF_NAME" dist/*.zip dist/*.zip.sha256 dist/SHA256SUMS \ --repo "$GITHUB_REPOSITORY" --draft --verify-tag --title "PythonTap ${GITHUB_REF_NAME#v}" \ --notes "See CHANGELOG.md for what changed. Unzip into Documents/Max 9/Packages; the Python runtime is included. On a Mac, choose arm64 for Apple Silicon or x86_64 for Intel (or for Max running under Rosetta)." diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index db27ca2..0cb88db 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -267,7 +267,10 @@ passed; a third ran the soak (6.2) and measured performance (6.3). To continue: the missing runtime; rename it back and create another: it should work without a restart. 6. *6.5 — the first release.* Tag a pre-1.0 version (`v0.9.0`), which runs `release.yml` for the first time, including the `macos-15-intel` runner; install each draft zip into `Packages/` - (clearing quarantine per the ReadMe) and repeat step 4's quick checks. + (clearing quarantine per the ReadMe) and repeat step 4's quick checks. *v0.9.0 is tagged and + its draft built; the Intel zip is checked (see 6.5).* For each other zip: unzip it into + `Packages/` as `PythonTap` in place of the checkout (move the checkout's link out of + `Packages/` meanwhile), then `python3 runtime-tests/run.py --package ~/Documents/Max\ 9/Packages/PythonTap`. - [x] **6.1 Runtime tests** with the `max-test` harness — `runtime-tests/`: Cycling '74's max-test as a submodule, the test patchers generated by `make_patchers.py` from scripts of steps, fixtures in @@ -316,7 +319,21 @@ passed; a third ran the soak (6.2) and measured performance (6.3). To continue: *Windows: by hand* (runbook step 5). - [ ] **6.5 The first release** (4.5) — tag a pre-1.0 version, check the draft's three zips install and run from `Packages/` on Apple Silicon, Intel (or Rosetta) and Windows; later, with - credentials, that signed and notarized packages load without the quarantine step. + credentials, that signed and notarized packages load without the quarantine step. *Tagged + `v0.9.0` (2026-09-30):* `release.yml`'s first run passed all four jobs and made the draft (three + zips, unsigned). *Intel checked:* the x86_64 zip, its checksum verified and unzipped into + `Packages/`, passes the whole runtime suite on an Intel Mac with Max 9.1.5 — + `runtime-tests/run.py --package` tests an installed package. *Still to check:* the arm64 zip on + Apple Silicon, the Windows zip on Windows, and the quarantine step (a zip fetched with `gh` is + not quarantined). *Found:* the release attached `SHA256SUMS` but not the per-zip `.sha256` the + ReadMe promises (`release.yml` fixed; the draft's added by hand); the external's bundle + identifier is min's template, unexpanded — `com.74objects.${PRODUCT_NAME:rfc1034identifier}` — + to fix before signing and notarizing; and `docs/PRODUCTION-PLAN.md` ships inside the package. + *Observed, not explained:* with the release installed, Max's file database took 8–11 minutes to + report ready at each launch (seconds with the linked checkout; Max had also just been updated to + 9.1.5 and rebuilt its database) — the runner no longer waits for it, as tests opened by name do + not need it; and Max rewrote the installed package's reference page, which it never did through + the linked checkout (a clue for 6.8). - [x] **6.6 Text files default to ASCII** — found by 6.1: the interpreter is configured with `PyConfig_InitIsolatedConfig`, whose pre-configuration leaves the locale unconfigured and UTF-8 mode off, so in Max `open()` and `Path.read_text()` without `encoding=` decode as ASCII, whatever diff --git a/runtime-tests/README.md b/runtime-tests/README.md index 033e60d..25a16dc 100644 --- a/runtime-tests/README.md +++ b/runtime-tests/README.md @@ -12,8 +12,13 @@ python3 runtime-tests/run.py # everything (~2 minutes); exit status python3 runtime-tests/run.py --only reload -v python3 runtime-tests/run.py --session soak # the hour-long soak (plan 6.2) python3 runtime-tests/run.py --session perf # Max's CPU meter under load (plan 6.3, ~4 minutes) +python3 runtime-tests/run.py --package ~/Documents/Max\ 9/Packages/PythonTap # an installed release ``` +`--package` tests a package installed in `Packages` as `PythonTap` — a release zip unzipped there — +instead of this checkout: its external, its runtime and its `python/` folder; the harness, the +patchers and the fixtures still come from here (plan 6.5). + Needs macOS, Max 9 in `/Applications` (`--max` for another), the external built, the runtime installed, and the package in Max's `Packages` folder as `PythonTap` (see the ReadMe). Quit Max first: the runner launches its own, drives it over OSC (UDP 4791/4792 on localhost) and quits it. diff --git a/runtime-tests/run.py b/runtime-tests/run.py index af4db79..e493cbf 100644 --- a/runtime-tests/run.py +++ b/runtime-tests/run.py @@ -8,6 +8,7 @@ python3 runtime-tests/run.py --only reload -v # the main tests whose names contain "reload" python3 runtime-tests/run.py --session soak # the hour-long soak (plan 6.2), on its own python3 runtime-tests/run.py --session perf # Max's CPU meter under load (plan 6.3) + python3 runtime-tests/run.py --package ~/Documents/Max\ 9/Packages/PythonTap # an installed release Needs macOS with Max 9, the external built (cmake --build build), the runtime installed (scripts/install-runtime.sh), and the package in Max's Packages folder as "PythonTap". It launches @@ -51,10 +52,12 @@ PATCHERS = TESTS / "patchers" FIXTURES = TESTS / "python" LOGS = TESTS / "logs" -SCRIPTS_DIR = ROOT / "python" -SUPPORT = ROOT / "support" -SUPPORT_ASIDE = ROOT / "support.maxtest-aside" -EXTERNAL = ROOT / "externals" / "tap.python~.mxo" +# The package under test: this checkout, or with --package an installed one (use_package()). +PACKAGE = ROOT +SCRIPTS_DIR = PACKAGE / "python" +SUPPORT = PACKAGE / "support" +SUPPORT_ASIDE = PACKAGE / "support.maxtest-aside" +EXTERNAL = PACKAGE / "externals" / "tap.python~.mxo" OSCAR = HARNESS / "extensions" / "oscar.mxo" # Must match misc/max-test-config.json: Max listens on one port and sends to the other. @@ -196,8 +199,9 @@ def start(self) -> None: print(f" launching Max (console: {self.console_path.relative_to(ROOT)})") self.wait_for("/ping/return", 180, poll="/ping", every=2) self.db_path = self.wait_for("/testdb/path", 30, poll="/testdb/path?", every=2)[0] - print(" waiting for Max's file database") - self.wait_for("/db/ready", 600, poll="/db/ready?", every=2) + # Not waiting for Max's file database: the tests are opened by name, through the search + # path, which does not need it (the harness's own "run everything" does). With a release + # installed it has taken minutes to report ready. def run_test(self, name: str, timeout: float) -> float: """Open one test patcher and wait for it to terminate itself. Returns the seconds taken.""" @@ -331,6 +335,18 @@ def perf_results(session: MaxSession, after_id: int) -> dict: # ---- setting up and putting things back -------------------------------------------------------- +def use_package(package: Path) -> None: + """Test the package at `package` — a release unzipped into Packages, say — instead of this + checkout: its external, its runtime, its python/ folder. The harness, the test patchers and the + fixtures still come from here.""" + global PACKAGE, SCRIPTS_DIR, SUPPORT, SUPPORT_ASIDE, EXTERNAL + PACKAGE = package.resolve() + SCRIPTS_DIR = PACKAGE / "python" + SUPPORT = PACKAGE / "support" + SUPPORT_ASIDE = PACKAGE / "support.maxtest-aside" + EXTERNAL = PACKAGE / "externals" / "tap.python~.mxo" + + def check_prerequisites(max_app: Path, packages: Path) -> None: if sys.platform != "darwin": raise RunError("the runtime tests run on macOS only (they launch Max)") @@ -339,16 +355,17 @@ def check_prerequisites(max_app: Path, packages: Path) -> None: if subprocess.run(["pgrep", "-x", "Max"], capture_output=True).returncode == 0: raise RunError("Max is running — quit it first (the tests launch their own)") if not EXTERNAL.exists(): - raise RunError("the external is not built — cmake -S . -B build && cmake --build build") + raise RunError("the external is not built — cmake -S . -B build && cmake --build build" + if PACKAGE == ROOT else f"no external in {PACKAGE}") if not SUPPORT.exists(): - raise RunError("no runtime in support/ — run scripts/install-runtime.sh") + raise RunError(f"no runtime in {SUPPORT} — run scripts/install-runtime.sh") if not packages.is_dir(): raise RunError(f"no Max Packages folder at {packages} (use --packages)") ours = packages / "PythonTap" - if not ours.exists() or ours.resolve() != ROOT: - raise RunError(f"{ours} is not this checkout — clone the repo there or symlink it in " - f"(ln -s {ROOT} {ours})") - others = [p for p in packages.glob("*/externals/tap.python~.mxo") if p.resolve().parents[1] != ROOT] + if not ours.exists() or ours.resolve() != PACKAGE: + raise RunError(f"{ours} is not {PACKAGE} — clone the repo there or symlink it in " + f"(ln -s {PACKAGE} {ours})" if PACKAGE == ROOT else f"{ours} is not {PACKAGE}") + others = [p for p in packages.glob("*/externals/tap.python~.mxo") if p.resolve().parents[1] != PACKAGE] if others: raise RunError(f"another tap.python~ is installed, which Max could load instead: {others[0]}") if not (HARNESS / "source").is_dir(): @@ -423,7 +440,7 @@ def run_session(max_app: Path, name: str, steps: list, verbose: bool, timeout: f print(f"\n== session: {name}") session = MaxSession(max_app, name, verbose) expected = [s for s in steps if isinstance(s, str)] - first_id = 0 + first_id: int | None = None # the last test recorded before this session: its results come after try: session.start() first_id = last_test_id(session.db_path) @@ -439,11 +456,18 @@ def run_session(max_app: Path, name: str, steps: list, verbose: bool, timeout: f except RunError as error: print(f" ERROR: {error}") session.quit() - failures = report(session.db_path, first_id, expected) if session.db_path else [] + if first_id is None: # Max never got as far as a test + failures = [f"{test}: never ran" for test in expected] + for test in expected: + print(f" FAIL {test} (never ran)") + else: + failures = report(session.db_path, first_id, expected) failures.append(f"{name}: {error}") else: session.quit() failures = report(session.db_path, first_id, expected) + if first_id is None: + return failures if name == "soak": summary = soak_summary(session, first_id) (LOGS / "soak.summary").write_text(summary + "\n") @@ -468,10 +492,15 @@ def main() -> int: help="run only the main tests whose file names contain this (repeatable)") parser.add_argument("--timeout", type=float, default=180, help="seconds allowed per test patcher") parser.add_argument("--soak-timeout", type=float, default=120, help="minutes allowed for the soak") + parser.add_argument("--package", type=Path, + help="test the package installed here (e.g. a release unzipped into Packages as " + "PythonTap) instead of this checkout") parser.add_argument("--keep-link", action="store_true", help=f"leave runtime-tests/ linked into Packages (as {TEST_PACKAGE}) afterwards") parser.add_argument("-v", "--verbose", action="store_true", help="print the harness's log as it runs") args = parser.parse_args() + if args.package: + use_package(args.package) main_tests = sorted(p.name for p in PATCHERS.glob("*.maxtest.maxpat")) if args.only: From 067d452c278bf7036ad6ecefec9e74dc7d63c915 Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Wed, 30 Sep 2026 08:50:46 -0500 Subject: [PATCH 02/15] Shorter reload stalls: hand the GIL to a waiting thread after 0.5 ms (2.6) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- CHANGELOG.md | 9 ++ CLAUDE.md | 4 +- ReadMe.md | 2 +- core/bench/CMakeLists.txt | 40 ++++-- core/bench/reload_bench.cpp | 221 ++++++++++++++++++++++++++++++ core/include/tap/python/runtime.h | 14 ++ core/tests/test_realtime.cpp | 4 +- core/tests/test_runtime.cpp | 7 + core/tests/test_safety.cpp | 4 +- docs/PRODUCTION-PLAN.md | 12 +- 10 files changed, 295 insertions(+), 22 deletions(-) create mode 100644 core/bench/reload_bench.cpp diff --git a/CHANGELOG.md b/CHANGELOG.md index 5620543..b0c0fe5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,15 @@ breaking changes to the contract are allowed where they buy correctness (D5 in ## Unreleased +### Changed — reloads and the audio thread + +- **A reload no longer holds up the audio for its whole length.** The interpreter now hands itself + to a waiting thread after 0.5 ms instead of CPython's 5 ms, so the audio thread waits at most + about that long at a time while another thread — a reload, above all, which takes a few + milliseconds — runs Python. Measured at 96 kHz with 512-sample buffers and a save every 100 ms, + CPython's default made a buffer late in most runs (the worst took 45 ms); at 0.5 ms none was. + (Plan 2.6.) + ### Changed — the console on reload - **One line per save, however many objects share the file.** Every object used to post two lines diff --git a/CLAUDE.md b/CLAUDE.md index 9287afa..8a8aa06 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,7 +27,9 @@ its phases, and the audit findings behind them. Tick its items (with the PR) as `core/tests/python/` and the shipped examples copied alongside. Runs on Linux, including under ASan/UBSan and TSan. - **`core/bench/`** — `tap_python_bench` times `processor::process()` as Max's audio thread calls it - (plan 6.3), fastest of five runs. `scripts/update-perf-docs.py` builds it (Release), runs it, and + (plan 6.3); `tap_python_reload_bench` times the audio buffers while the class reloads, with the + audio thread scheduled as Core Audio's are (plan 2.6: why the runtime sets a 0.5 ms switch + interval). `scripts/update-perf-docs.py` builds it (Release), runs it, and rewrites the ReadMe's generated performance tables — with `--max`, Max's CPU meter too, through `runtime-tests/run.py --session perf`. Never hand-edit those tables; measure on an idle machine. - **`source/projects/tap.python_tilde/`** — the Min external: package paths, the file watcher, atom diff --git a/ReadMe.md b/ReadMe.md index 886f87e..cbe5c70 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -99,7 +99,7 @@ Python sources live in the package's `python` folder. `[tap.python~ name]` loads ### A note on performance -`process()` runs on the audio thread, holding Python's global interpreter lock. The per-sample form (`x: float`) makes one Python call per sample. The call itself is cheap — a fraction of a percent of a core, in the measurements below — but every line of Python in it runs 48,000 or 96,000 times a second, so the cost is your code's: `allpass.py`, a few lines of indexing and arithmetic, costs more than twenty times the call — and `numpy_allpass.py`, the same filter written a vector at a time, a small fraction of it. It is fantastic for sketching and live-coding an algorithm. The numpy form (`x: np.ndarray`) makes one call per signal vector, and numpy then works on the whole vector at C speed: it is the one to use when the algorithm has real work in it and has to keep up. Either way the audio thread waits while other Python code holds the interpreter — a reload, a message, or another instance: all `tap.python~` instances share one interpreter, so heavy Python work in one can steal time from the others. Errors in `process()` are printed from Max's main thread, never from the audio thread. +`process()` runs on the audio thread, holding Python's global interpreter lock. The per-sample form (`x: float`) makes one Python call per sample. The call itself is cheap — a fraction of a percent of a core, in the measurements below — but every line of Python in it runs 48,000 or 96,000 times a second, so the cost is your code's: `allpass.py`, a few lines of indexing and arithmetic, costs more than twenty times the call — and `numpy_allpass.py`, the same filter written a vector at a time, a small fraction of it. It is fantastic for sketching and live-coding an algorithm. The numpy form (`x: np.ndarray`) makes one call per signal vector, and numpy then works on the whole vector at C speed: it is the one to use when the algorithm has real work in it and has to keep up. Either way the audio thread waits while other Python code holds the interpreter — a reload, a message, or another instance: all `tap.python~` instances share one interpreter, so heavy Python work in one can steal time from the others. The object has Python hand the interpreter to a waiting thread after half a millisecond — a tenth of CPython's default — so a reload, which holds it for a few milliseconds, delays the audio a little at a time instead of all at once: measured with `core/bench`'s reload benchmark (96 kHz, 512-sample buffers, a save every 100 ms), no buffer was late at 0.5 ms, where CPython's default left some late in most runs. Errors in `process()` are printed from Max's main thread, never from the audio thread. What `process()` costs, measured by `core/bench` — which calls it exactly as Max's audio thread does, one vector at a time — as the share of one CPU core it needs: diff --git a/core/bench/CMakeLists.txt b/core/bench/CMakeLists.txt index 690b91d..7e681e7 100644 --- a/core/bench/CMakeLists.txt +++ b/core/bench/CMakeLists.txt @@ -12,24 +12,34 @@ execute_process( COMMAND_ERROR_IS_FATAL ANY ) -add_executable(tap_python_bench process_bench.cpp) -target_link_libraries(tap_python_bench PRIVATE tap::python Python3::Python) - set(_scripts_dir "${CMAKE_CURRENT_BINARY_DIR}/scripts") -target_compile_definitions(tap_python_bench PRIVATE - TAP_PYTHON_BENCH_HOME="${TAP_PYTHON_BENCH_HOME}" - TAP_PYTHON_BENCH_SCRIPTS_DIR="${_scripts_dir}" -) -if (MSVC) - target_compile_options(tap_python_bench PRIVATE /W4) -else () - target_compile_options(tap_python_bench PRIVATE -Wall -Wextra) -endif () - -# The script folder: the benchmark's own classes plus the package's shipped examples. -add_custom_command(TARGET tap_python_bench POST_BUILD +# The script folder: the benchmarks' own classes plus the package's shipped examples. +add_custom_target(tap_python_bench_scripts COMMAND "${CMAKE_COMMAND}" -E make_directory "${_scripts_dir}" COMMAND "${CMAKE_COMMAND}" -E copy_directory "${CMAKE_CURRENT_SOURCE_DIR}/python" "${_scripts_dir}" COMMAND "${CMAKE_COMMAND}" -E copy_directory "${CMAKE_CURRENT_SOURCE_DIR}/../../python" "${_scripts_dir}" ) + +# tap_python_bench: what process() costs (6.3); tap_python_reload_bench: what a reload costs the +# audio thread (2.6) +foreach (_bench IN ITEMS tap_python_bench tap_python_reload_bench) + if (_bench STREQUAL "tap_python_bench") + add_executable(${_bench} process_bench.cpp) + else () + add_executable(${_bench} reload_bench.cpp) + endif () + target_link_libraries(${_bench} PRIVATE tap::python Python3::Python) + add_dependencies(${_bench} tap_python_bench_scripts) + target_compile_definitions(${_bench} PRIVATE + TAP_PYTHON_BENCH_HOME="${TAP_PYTHON_BENCH_HOME}" + TAP_PYTHON_BENCH_SCRIPTS_DIR="${_scripts_dir}" + ) + if (MSVC) + target_compile_options(${_bench} PRIVATE /W4) + else () + target_compile_options(${_bench} PRIVATE -Wall -Wextra) + endif () +endforeach () +find_package(Threads REQUIRED) +target_link_libraries(tap_python_reload_bench PRIVATE Threads::Threads) diff --git a/core/bench/reload_bench.cpp b/core/bench/reload_bench.cpp new file mode 100644 index 0000000..4503c21 --- /dev/null +++ b/core/bench/reload_bench.cpp @@ -0,0 +1,221 @@ +/// @file reload_bench.cpp +/// @brief What a reload costs the audio thread: how long process() waits while load() runs (plan 2.6). +// SPDX-License-Identifier: MIT +// Copyright 2022-2026 Timothy Place. +// +// An audio thread plays Max's audio callback: every I/O buffer (512 samples) it calls +// processor::process() for each signal vector in it (64 samples), back to back, and times the +// buffer — scheduled as a real-time audio thread, so that other work on the machine does not +// preempt it. The main thread saves the class file with a new revision and reloads it every so +// often, as the object does on a save. load() holds the GIL to compile, run and describe the class, +// so a process() that arrives meanwhile waits: CPython makes the holder let go after its switch +// interval (5 ms by default), and never inside a long run of C code. A buffer not done within its +// period is a dropout. +// +// tap_python_reload_bench # the default switch interval, then smaller ones +// tap_python_reload_bench --seconds 10 --every 50 + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include "tap/python/processor.h" +#include "tap/python/runtime.h" + +#ifdef __APPLE__ +#include +#include +#include +#include +#include +#endif + +namespace { + + using tap::python::processor; + using clock_type = std::chrono::steady_clock; + + constexpr double k_sample_rate = 96000.0; + constexpr std::size_t k_vector_size = 64; + constexpr std::size_t k_io_size = 512; // an I/O buffer: 8 vectors, computed in one go + constexpr double k_quiet_seconds = 2.0; + constexpr double k_switch_intervals[] = {0.005, 0.001, 0.0005, 0.0002, 0.0001}; // seconds; CPython's default first + + struct subject { + const char* name; // the class written for the benchmark + const char* example; // the shipped example it copies + }; + constexpr subject k_subjects[] = {{"bench_reload_sample", "allpass"}, {"bench_reload_block", "numpy_allpass"}}; + + std::string read_file(const std::string& path) { + std::ifstream in{path}; + std::ostringstream text; + text << in.rdbuf(); + return text.str(); + } + + /// The example's source as class `name`, at `revision`: each revision is a real change, so + /// every reload compiles and runs the file again. + std::string revision_source(const std::string& example_source, const std::string& example, const std::string& name, + const int revision) { + std::string source = example_source; + const auto statement = "class " + example + ":"; + source.replace(source.find(statement), statement.size(), "class " + name + ":"); + return "REVISION = " + std::to_string(revision) + "\n" + source; + } + + /// Schedule the calling thread as an audio thread is (macOS: the time-constraint policy Core + /// Audio's I/O threads use), so that other work on the machine does not preempt it and the + /// measurement shows the wait for the GIL rather than the machine's load. + void make_realtime(const double period_seconds) { +#ifdef __APPLE__ + mach_timebase_info_data_t timebase{}; + mach_timebase_info(&timebase); + const auto ticks = [&](const double seconds) { + return static_cast(seconds * 1e9 * timebase.denom / timebase.numer); + }; + thread_time_constraint_policy_data_t policy{ticks(period_seconds), ticks(period_seconds * 0.5), + ticks(period_seconds), 1}; + thread_policy_set(pthread_mach_thread_np(pthread_self()), THREAD_TIME_CONSTRAINT_POLICY, + reinterpret_cast(&policy), THREAD_TIME_CONSTRAINT_POLICY_COUNT); +#else + (void)period_seconds; +#endif + } + + /// The main thread, as a user-facing app's is (macOS: the user-interactive QoS class). + void make_interactive() { +#ifdef __APPLE__ + pthread_set_qos_class_self_np(QOS_CLASS_USER_INTERACTIVE, 0); +#endif + } + + struct summary { + double median{}; + double p99{}; + double max{}; + }; + + summary summarize(std::vector microseconds) { + if (microseconds.empty()) { + return {}; + } + std::sort(microseconds.begin(), microseconds.end()); + return {microseconds[microseconds.size() / 2], microseconds[microseconds.size() * 99 / 100], + microseconds.back()}; + } + + void run_case(const subject& s, const std::string& scripts, const double switch_interval, const double seconds, + const int every_ms) { + const auto example_source = read_file(scripts + "/" + s.example + ".py"); + const auto path = scripts + "/" + s.name + ".py"; + int revision = 0; + std::ofstream{path, std::ios::trunc} << revision_source(example_source, s.example, s.name, revision); + + processor p{s.name, [](auto, auto) {}}; + if (!p.load()) { + std::fprintf(stderr, "could not load %s\n", s.name); + std::exit(1); + } + p.prepare(k_sample_rate, k_vector_size); + { + tap::python::gil_lock lock; + PyRun_SimpleString(("import sys\nsys.setswitchinterval(" + std::to_string(switch_interval) + ")").c_str()); + } + + const auto period = + std::chrono::duration_cast(std::chrono::duration{k_io_size / k_sample_rate}); + const auto vectors = static_cast((k_quiet_seconds + seconds) * k_sample_rate / k_io_size); + std::vector quiet; + std::vector reloading; + quiet.reserve(vectors); + reloading.reserve(vectors); + std::atomic stop{false}; + std::atomic busy{false}; // the main thread has started reloading + + std::thread audio{[&] { + make_realtime(k_io_size / k_sample_rate); + std::vector in(k_vector_size, 0.25); + std::vector out(k_vector_size); + auto next = clock_type::now(); + while (!stop.load()) { + std::this_thread::sleep_until(next); + next += period; + const auto start = clock_type::now(); + for (std::size_t v = 0; v < k_io_size / k_vector_size; ++v) { + p.process(in.data(), out.data(), k_vector_size); + } + const std::chrono::duration took = clock_type::now() - start; + (busy.load() ? reloading : quiet).push_back(took.count()); + } + }}; + + std::this_thread::sleep_for(std::chrono::duration{k_quiet_seconds}); + busy = true; + std::vector loads; + const auto until = clock_type::now() + std::chrono::duration{seconds}; + while (clock_type::now() < until) { + std::ofstream{path, std::ios::trunc} << revision_source(example_source, s.example, s.name, ++revision); + const auto start = clock_type::now(); + p.load(); + const std::chrono::duration took = clock_type::now() - start; + loads.push_back(took.count()); + std::this_thread::sleep_for(std::chrono::milliseconds{every_ms}); + } + stop = true; + audio.join(); + + const auto q = summarize(quiet); + const auto r = summarize(reloading); + const auto l = summarize(loads); + const double deadline = std::chrono::duration{period}.count(); + const auto late = std::count_if(reloading.begin(), reloading.end(), [&](double t) { return t > deadline; }); + std::printf( + "%-20s switch %5.2f ms | buffer: quiet p50 %6.0f max %6.0f us | reloading p50 %6.0f p99 %6.0f max %6.0f us" + " | %3zu of %5zu buffers over %.0f us | load p50 %5.0f max %6.0f us (%zu)\n", + s.name, switch_interval * 1000.0, q.median, q.max, r.median, r.p99, r.max, static_cast(late), + reloading.size(), deadline, l.median, l.max, loads.size()); + } + +} // namespace + +int main(int argc, char** argv) { + double seconds = 5.0; + int every_ms = 100; + for (int i = 1; i < argc; ++i) { + const std::string_view arg{argv[i]}; + if (arg == "--seconds" && i + 1 < argc) { + seconds = std::atof(argv[++i]); + } + else if (arg == "--every" && i + 1 < argc) { + every_ms = std::max(1, std::atoi(argv[++i])); + } + else { + std::fprintf(stderr, "usage: %s [--seconds ] [--every ]\n", argv[0]); + return 2; + } + } + + make_interactive(); + const auto status = tap::python::initialize({TAP_PYTHON_BENCH_HOME, TAP_PYTHON_BENCH_SCRIPTS_DIR, {}}); + if (!status.ok) { + std::fprintf(stderr, "could not start Python: %s\n", status.error.c_str()); + return 1; + } + std::printf("96 kHz, 64-sample vectors in 512-sample buffers (a %.0f us period); a save and reload every %d ms\n", + k_io_size / k_sample_rate * 1e6, every_ms); + for (const auto& s : k_subjects) { + for (const double interval : k_switch_intervals) { + run_case(s, TAP_PYTHON_BENCH_SCRIPTS_DIR, interval, seconds, every_ms); + } + } + return 0; +} diff --git a/core/include/tap/python/runtime.h b/core/include/tap/python/runtime.h index a071f52..765c8ca 100644 --- a/core/include/tap/python/runtime.h +++ b/core/include/tap/python/runtime.h @@ -35,6 +35,11 @@ namespace tap::python { std::filesystem::path home; ///< the CPython installation (PyConfig.home) std::filesystem::path scripts_dir; ///< the user's script folder, made importable log_function console; ///< where Python's stdout (info) and stderr (error) go + /// How long a thread holding the GIL keeps it from a thread waiting for it, in seconds + /// (sys.setswitchinterval). CPython's 5 ms lets a reload on the main thread keep the audio + /// thread waiting past an I/O buffer's deadline; 0.5 ms does not (plan 2.6: measured by + /// core/bench's tap_python_reload_bench) and is under one 64-sample vector at 96 kHz. + double switch_interval = 0.0005; }; /// The outcome of initialize(): ok, or the reason the interpreter could not start. @@ -498,6 +503,15 @@ def describe(fn): detail::create_support(); + // 2.6: hand the GIL to a waiting thread — the audio thread, above all — sooner + if (PyObject* set_interval = PySys_GetObject("setswitchinterval")) { // borrowed + PyObject* seconds = PyFloat_FromDouble(options.switch_interval); + PyObject* result = seconds ? PyObject_CallOneArg(set_interval, seconds) : nullptr; + Py_XDECREF(result); + Py_XDECREF(seconds); + } + PyErr_Clear(); + // Route print() and tracebacks to the host console. // sys.stdout/sys.stderr are text streams (io.TextIOBase) so that libraries which probe them // — encoding, errors, isatty(), fileno() — find what they expect; flush() forwards a diff --git a/core/tests/test_realtime.cpp b/core/tests/test_realtime.cpp index 21a2e37..a56fb26 100644 --- a/core/tests/test_realtime.cpp +++ b/core/tests/test_realtime.cpp @@ -233,7 +233,7 @@ SCENARIO("prepare() while block audio runs never crashes or corrupts a vector") processor p{"block_gain"}; REQUIRE(p.load()); p.prepare(48000.0, 64); - REQUIRE(run("import sys\nsys.setswitchinterval(1e-6)")); + REQUIRE(run("import sys\n_switch_interval = sys.getswitchinterval()\nsys.setswitchinterval(1e-6)")); std::atomic stop{false}; std::atomic wrong{0}; @@ -259,7 +259,7 @@ SCENARIO("prepare() while block audio runs never crashes or corrupts a vector") } stop = true; audio.join(); - REQUIRE(run("import sys\nsys.setswitchinterval(0.005)")); + REQUIRE(run("import sys\nsys.setswitchinterval(_switch_interval)")); CHECK(wrong.load() == 0); } diff --git a/core/tests/test_runtime.cpp b/core/tests/test_runtime.cpp index 0790651..3d2fa0d 100644 --- a/core/tests/test_runtime.cpp +++ b/core/tests/test_runtime.cpp @@ -125,3 +125,10 @@ SCENARIO("Text is UTF-8 by default, whatever the host's locale (plan 6.6)") { } } } + +SCENARIO("A thread waiting for the GIL gets it within half a millisecond (plan 2.6)") { + ensure_runtime(); + // CPython's 5 ms let a reload keep the audio thread waiting past an I/O buffer's deadline + // (core/bench/reload_bench.cpp measures it); the runtime sets 0.5 ms + CHECK(run("import sys\nassert sys.getswitchinterval() == 0.0005, sys.getswitchinterval()\n")); +} diff --git a/core/tests/test_safety.cpp b/core/tests/test_safety.cpp index c9191cd..bb4ed09 100644 --- a/core/tests/test_safety.cpp +++ b/core/tests/test_safety.cpp @@ -94,7 +94,7 @@ SCENARIO("Reloading while audio runs never crashes and never interrupts the audi REQUIRE(p.load()); // make GIL hand-offs as frequent as possible, so reloads land mid-vector - REQUIRE(run("import sys\nsys.setswitchinterval(1e-6)")); + REQUIRE(run("import sys\n_switch_interval = sys.getswitchinterval()\nsys.setswitchinterval(1e-6)")); std::atomic stop{false}; std::atomic wrong_samples{0}; @@ -125,7 +125,7 @@ SCENARIO("Reloading while audio runs never crashes and never interrupts the audi } stop = true; audio.join(); - REQUIRE(run("import sys\nsys.setswitchinterval(0.005)")); + REQUIRE(run("import sys\nsys.setswitchinterval(_switch_interval)")); CHECK(reloads == 200); CHECK(wrong_samples.load() == 0); // no silent (or partial) vectors across 200 reloads diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index 0cb88db..2275bf3 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -104,7 +104,17 @@ while audio ran segfaulted in 5 of 5 runs. return defines outlets, fixed at construction. - [ ] **2.5 Worker mode (D1)** — `@mode worker`: Python on a worker thread, lock-free FIFO, latency reported to Max, underrun → silence. -- [ ] **2.6 Shorter reload stalls** — compile outside the swap and hold the GIL only for the swap. +- [x] **2.6 Shorter reload stalls** — compile outside the swap and hold the GIL only for the swap. + *Measured first* (`core/bench/reload_bench.cpp`: an audio thread with Core Audio's real-time + scheduling computes 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). + *Done:* the runtime sets a 0.5 ms switch interval (`runtime_options::switch_interval`): no late + buffer in three runs, the 99th percentile 0.7–2 ms, the median unchanged. 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 very large class file would still + compile in one piece (2.5, worker mode, is the answer to that). ## Phase 3 — the type bridge and class contract From 4e18eee77cf5a3a7acfeaf47e3ff3d01d629a7b8 Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Wed, 30 Sep 2026 09:29:02 -0500 Subject: [PATCH 03/15] One traceback per broken save, however many objects share the file (6.10) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- CHANGELOG.md | 9 + CLAUDE.md | 5 +- ReadMe.md | 2 +- core/include/tap/python/processor.h | 6 +- core/include/tap/python/runtime.h | 59 +- core/tests/support.h | 15 +- core/tests/test_processor.cpp | 58 ++ docs/PRODUCTION-PLAN.md | 9 +- runtime-tests/make_patchers.py | 8 +- .../tap.python~.announce-once.maxtest.maxpat | 796 ++++++++++++++---- runtime-tests/run.py | 6 + 11 files changed, 782 insertions(+), 191 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b0c0fe5..2e369e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,15 @@ breaking changes to the contract are allowed where they buy correctness (D5 in ## Unreleased +### Changed — a broken file is reported once + +- **A save that breaks a class file is reported once, however many objects share it.** Every + object used to run the file and print its traceback: a syntax error with 25 objects printed 25 + tracebacks. Now a failure of the same source already reported in the last two seconds — the + same save, or a patch opening many objects at once — is not reported again, while an object + created later with the file still broken says why it is silent. Every load still runs the file, + in case something it imports has been fixed. (Plan 6.10.) + ### Changed — reloads and the audio thread - **A reload no longer holds up the audio for its whole length.** The interpreter now hands itself diff --git a/CLAUDE.md b/CLAUDE.md index 8a8aa06..c85a86d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -122,8 +122,9 @@ the secrets exist, and attaches zips + SHA256s to a draft release. - **Say what is true of a class once, what is true of an instance per instance.** Many objects can share one class file; only the processor whose `load()` ran the file (`load_script` says so) announces the class — its `Loaded` line and its diagnostics — through `announce()` (plan 6.7). - Use `log()` only for what concerns one instance. Tests that load a file again and check what was - announced call `forget_loaded()` first. + Use `log()` only for what concerns one instance. A file that fails to load is reported once too: + the loader marks a failure of the same source it reported under two seconds ago (6.10). Tests + that load a file again and check what was announced or reported call `forget_loaded()` first. - Report user exceptions with `tap::python::report_exception()`, **never `PyErr_Print()`**: for a `SystemExit` it calls `Py_Exit()` and quits Max. Never finalize the interpreter, and never let a C++ exception cross a Max callback (the trampolines are wrapped in `guarded()`). diff --git a/ReadMe.md b/ReadMe.md index cbe5c70..f66377e 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -94,7 +94,7 @@ Python sources live in the package's `python` folder. `[tap.python~ name]` loads One signal inlet and one signal outlet, single-channel; wrap the object in `mc.` for multichannel. (Returning a tuple for multiple outputs is not supported yet.) Output that is not a number, or not finite (NaN, infinity), is replaced with 0.0 and reported once in the Max console. - **Audio settings** — an optional method `prepare(self, sample_rate: float, vector_size: int) -> None` is called with Max's sample rate and vector size before the object processes any audio, again whenever they change, and on every reload before the new code runs. `python/allpass.py` uses it to size its delay line. -- **Hot reload** — saving the `.py` file reloads it in place, as a fresh module (names you deleted from the file are gone): the attributes and messages follow the new class, and audio resumes with the new code. Until the new code is ready the object keeps running the old one, so a successful reload swaps in without a gap in the audio. Attribute values carry over — set from the patcher or by your own code — for every attribute the new class still has with the same type; an attribute whose type changed starts from its new default, and one you removed disappears from the object. If the file has an error, the object prints the traceback to the Max console and outputs silence until the next successful reload (and the attribute values come back with it). Every object using the same file shares one execution of it per save, and the console says so once — `Loaded name.py: process() bound, one call per sample` (or per vector), from whichever object ran the file — along with anything true of the class, such as a method skipped for its name; a save that changes nothing reloads silently. Errors that belong to one object, such as an exception in its constructor, are still reported by each. Max's file watcher notices a save within a couple of seconds, but it coalesces saves made in quick succession — a script saving once a second, say — so the object then reloads for only some of them, and can lag behind until they stop; sending the object `filechanged` reloads it at once. +- **Hot reload** — saving the `.py` file reloads it in place, as a fresh module (names you deleted from the file are gone): the attributes and messages follow the new class, and audio resumes with the new code. Until the new code is ready the object keeps running the old one, so a successful reload swaps in without a gap in the audio. Attribute values carry over — set from the patcher or by your own code — for every attribute the new class still has with the same type; an attribute whose type changed starts from its new default, and one you removed disappears from the object. If the file has an error, the object prints the traceback to the Max console and outputs silence until the next successful reload (and the attribute values come back with it); a save that breaks a file shared by many objects is reported once, not by each, while an object created later with the file still broken says so again. Every object using the same file shares one execution of it per save, and the console says so once — `Loaded name.py: process() bound, one call per sample` (or per vector), from whichever object ran the file — along with anything true of the class, such as a method skipped for its name; a save that changes nothing reloads silently. Errors that belong to one object, such as an exception in its constructor, are still reported by each. Max's file watcher notices a save within a couple of seconds, but it coalesces saves made in quick succession — a script saving once a second, say — so the object then reloads for only some of them, and can lag behind until they stop; sending the object `filechanged` reloads it at once. - **Errors** — an exception raised by your code (in `process()`, a message, an attribute setter, the constructor or at import) prints its traceback to the Max console; it never takes Max down. That includes `sys.exit()`, which is reported like any other exception rather than quitting Max. ### A note on performance diff --git a/core/include/tap/python/processor.h b/core/include/tap/python/processor.h index e21d06d..75eae34 100644 --- a/core/include/tap/python/processor.h +++ b/core/include/tap/python/processor.h @@ -158,8 +158,10 @@ namespace tap::python { // per execution of the file, by the processor that ran it; the others sharing it are quiet m_announcing = executed; if (!module) { - report_exception(); - log(log_level::error, "Failed to load " + path.string()); + if (!take_reported_load_failure()) { // 6.10: once per failing save, not per object + report_exception(); + log(log_level::error, "Failed to load " + path.string()); + } release_binding(); return false; } diff --git a/core/include/tap/python/runtime.h b/core/include/tap/python/runtime.h index 765c8ca..b44a903 100644 --- a/core/include/tap/python/runtime.h +++ b/core/include/tap/python/runtime.h @@ -173,7 +173,11 @@ namespace tap::python { // save — and executes it as a fresh module registered in sys.modules under module_name (typing // and attrs resolve annotations through sys.modules). Modules are cached by source: loading an // unchanged file returns the module already executed, so every instance of one file shares a - // single execution per save. On failure the previous module stays registered. + // single execution per save. On failure the previous module stays registered, and the file is + // run again by the next load (something it imports may have been fixed) — but a failure of the + // same source already reported within _REPORT_WINDOW seconds is marked _tap_python_reported, + // so that a save that breaks a file shared by many objects, or a patch opening many of them, + // reports it once, while an object created later still says why it is silent (plan 6.10). // // hint_kind(hint) -> str. The name the host maps a type hint by: 'int', 'float', 'bool', 'str', // 'ndarray', 'tuple', ... ('any' for no hint, 'ClassVar' for a class variable). Optional[X] and @@ -190,9 +194,11 @@ namespace tap::python { // describe(callable) -> ([(name, kind, parameter_kind, has_default)], return_kind, error). // parameter_kind is inspect.Parameter.kind as an int. inline constexpr const char* k_support_source = R"( -import inspect, re, sys, types, typing +import inspect, re, sys, time, types, typing _cache = {} +_failed = {} +_REPORT_WINDOW = 2.0 def load(module_name, path): with open(path, 'rb') as f: @@ -200,19 +206,32 @@ def load(module_name, path): cached = _cache.get(module_name) if cached is not None and cached[0] == source: return cached[1], False - code = compile(source, path, 'exec', dont_inherit=True) - module = types.ModuleType(module_name) - module.__file__ = path - previous = sys.modules.get(module_name) - sys.modules[module_name] = module try: - exec(code, module.__dict__) - except BaseException: - if previous is not None: - sys.modules[module_name] = previous + code = compile(source, path, 'exec', dont_inherit=True) + module = types.ModuleType(module_name) + module.__file__ = path + previous = sys.modules.get(module_name) + sys.modules[module_name] = module + try: + exec(code, module.__dict__) + except BaseException: + if previous is not None: + sys.modules[module_name] = previous + else: + sys.modules.pop(module_name, None) + raise + except BaseException as error: + now = time.monotonic() + last = _failed.get(module_name) + if last is not None and last[0] == source and now - last[1] < _REPORT_WINDOW: + try: + error._tap_python_reported = True + except Exception: + pass else: - sys.modules.pop(module_name, None) + _failed[module_name] = (source, now) raise + _failed.pop(module_name, None) _cache[module_name] = (source, module) return module, True @@ -391,6 +410,22 @@ def describe(fn): /// host process — so user code calling sys.exit() would quit Max. Here a SystemExit is reported /// like any other exception. It also leaves sys.last_exc unset, so a failed call does not keep /// its frames (and the objects they reference) alive. + /// True — clearing it — when the raised exception is a failure to load a file that was reported + /// moments ago by another processor loading the same source (see load() in the support module): + /// said once, not once per object sharing the file. False, leaving it raised, otherwise. + inline bool take_reported_load_failure() { + PyObject* exception = PyErr_GetRaisedException(); + if (!exception) { + return false; + } + if (PyObject_HasAttrString(exception, "_tap_python_reported") == 1) { + Py_DECREF(exception); + return true; + } + PyErr_SetRaisedException(exception); // steals the reference + return false; + } + inline void report_exception() { PyObject* exception = PyErr_GetRaisedException(); if (!exception) { diff --git a/core/tests/support.h b/core/tests/support.h index 39da4aa..6191b58 100644 --- a/core/tests/support.h +++ b/core/tests/support.h @@ -99,14 +99,17 @@ namespace tap::python::test { return PyRun_SimpleString(source.c_str()) == 0; } - /// Forget which revision of `.py` was last run, so that the next load() runs it again — - /// and so says what is true of its class, as a first load in a fresh process does (plan 6.7). - /// For scenarios whose sections load the same file again and check what the load logged. + /// Forget which revision of `.py` was last run, or last failed, so that the next load() + /// says what is true of its class, or why it failed, as a first load in a fresh process does + /// (plan 6.7, 6.10). For scenarios whose sections load the same file again and check what the + /// load logged. inline void forget_loaded(const std::string& name) { gil_lock lock; - if (PyObject* cache = detail::support("_cache")) { // borrowed - if (PyDict_DelItemString(cache, ("_tap_python_" + name).c_str()) != 0) { - PyErr_Clear(); // not loaded yet + for (const char* record : {"_cache", "_failed"}) { + if (PyObject* table = detail::support(record)) { // borrowed + if (PyDict_DelItemString(table, ("_tap_python_" + name).c_str()) != 0) { + PyErr_Clear(); // not loaded, or not failed, yet + } } } } diff --git a/core/tests/test_processor.cpp b/core/tests/test_processor.cpp index 135c61f..fc247e5 100644 --- a/core/tests/test_processor.cpp +++ b/core/tests/test_processor.cpp @@ -444,3 +444,61 @@ SCENARIO("A file's load is announced once, by the processor that ran it (plan 6. } } } + +SCENARIO("A file that fails to load is reported once per save, not once per object (plan 6.10)") { + ensure_runtime(); + write_script("broken_once", "class broken_once:\n" + " def process(self, x: float) -> float:\n" + " return x\n\n" + "def (\n"); + forget_loaded("broken_once"); + const auto syntax_errors = [] { + const auto lines = console().lines(); + return std::count_if(lines.begin(), lines.end(), [](const log_capture::line& l) { + return l.level == log_level::error && l.text.find("SyntaxError:") != std::string::npos; + }); + }; + log_capture first_log; + log_capture second_log; + processor first{"broken_once", first_log.sink()}; + processor second{"broken_once", second_log.sink()}; + console().clear(); + CHECK_FALSE(first.load()); + CHECK_FALSE(second.load()); + + THEN("the first to load it says why, once; the other is quiet — and silent") { + CHECK(first_log.contains("Failed to load", log_level::error)); + CHECK(second_log.lines().empty()); + CHECK(syntax_errors() == 1); + CHECK(all_equal(render(second, 0.5), 0.0)); + } + WHEN("the file is saved broken another way") { + first_log.clear(); + second_log.clear(); + console().clear(); + write_script("broken_once", "class broken_once:\n pass\n\n)\n"); + CHECK_FALSE(second.load()); + CHECK_FALSE(first.load()); + THEN("that save is reported, once") { + CHECK(second_log.contains("Failed to load", log_level::error)); + CHECK(first_log.lines().empty()); + CHECK(syntax_errors() == 1); + } + } + WHEN("an object is made later, with the file still broken") { + const auto set_window = [](const double seconds) { // "later": past the loader's window + gil_lock lock; + PyObject* value = PyFloat_FromDouble(seconds); + PyDict_SetItemString(detail::support_globals(), "_REPORT_WINDOW", value); + Py_DECREF(value); + }; + set_window(0.0); + log_capture later_log; + processor later{"broken_once", later_log.sink()}; + CHECK_FALSE(later.load()); + set_window(2.0); + THEN("it says why it is silent") { + CHECK(later_log.contains("Failed to load", log_level::error)); + } + } +} diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index 2275bf3..76ab71f 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -375,11 +375,16 @@ passed; a third ran the soak (6.2) and measured performance (6.3). To continue: - [ ] **6.9 The help patcher and `numpy_allpass.py`** — the help patcher points to the `numpy_gain` and `allpass` examples but not to `numpy_allpass`, the one that shows what the block path is for; add it in Max (and re-save), perhaps with the measured comparison. -- [ ] **6.10 One traceback per broken save** — a file that fails to load is not cached, so every +- [x] **6.10 One traceback per broken save** — a file that fails to load is not cached, so every object sharing it runs it and prints the traceback: 25 objects, 25 tracebacks. 6.7 left this alone, because the obvious fix — remember the failing source and stay quiet — would also hide the error from an object created later (a patch reopened with the file still broken). Needs a - rule that reports once per save without that. + rule that reports once per save without that. *Done:* the loader still runs the file on every + load, but marks a failure of the same source it reported less than two seconds ago + (`_REPORT_WINDOW`), and the processor stays quiet for a marked failure — a save, or a patch + opening many objects, reports once; an object made later reports again. Pinned by a core test + (two processors; another broken save; a later object) and the runtime test `announce-once` (a + broken save, five objects in Max, one report — five before the change). ## Phase 7 — plugin front ends (optional, post-1.0) diff --git a/runtime-tests/make_patchers.py b/runtime-tests/make_patchers.py index 6a646dc..2c25b76 100644 --- a/runtime-tests/make_patchers.py +++ b/runtime-tests/make_patchers.py @@ -561,7 +561,8 @@ def announce_once() -> Test: t = Test("tap.python~.announce-once.maxtest.maxpat", "What is true of a class is said once per run of its file, however many objects share it " "(plan 6.7): five instances of a class with a reserved method name, reporting it once on " - "load, once more after the file changes, and not at all when an unchanged file reloads.", + "load, once more after the file changes, and not at all when an unchanged file reloads; " + "and a save that breaks the file is reported once, not by each (plan 6.10).", audio=False) host = t.host() # loaded by the first step, so that what the objects print is caught editor = t.python("maxtest_editor", column=1) @@ -573,6 +574,11 @@ def announce_once() -> Test: t.step(t.errors_are("said-once-more-after-a-change", "== 2", pattern)) t.step(t.send("filechanged", host)) t.step(t.errors_are("unchanged-reload-says-nothing", "== 2", pattern), wait=WATCH) + # 6.10: a save that breaks the file is reported once, not by each of the five + t.count_errors("Failed.to.load") + t.step(t.send("corrupt maxtest_reserved", editor)) # the file watcher reloads them all + t.step(t.errors_are("broken-save-reported-once-for-five-objects", "== 1", "Failed.to.load"), wait=WATCH) + t.step(t.send("restore maxtest_reserved", editor)) return t diff --git a/runtime-tests/patchers/tap.python~.announce-once.maxtest.maxpat b/runtime-tests/patchers/tap.python~.announce-once.maxtest.maxpat index 7f529b0..811ef1c 100644 --- a/runtime-tests/patchers/tap.python~.announce-once.maxtest.maxpat +++ b/runtime-tests/patchers/tap.python~.announce-once.maxtest.maxpat @@ -13,7 +13,7 @@ 60.0, 80.0, 1290, - 628.0 + 808.0 ], "default_fontsize": 12.0, "default_fontname": "Arial", @@ -35,7 +35,7 @@ 480, 80.0 ], - "text": "tap.python~.announce-once\n\nWhat is true of a class is said once per run of its file, however many objects share it (plan 6.7): five instances of a class with a reserved method name, reporting it once on load, once more after the file changes, and not at all when an unchanged file reloads.", + "text": "tap.python~.announce-once\n\nWhat is true of a class is said once per run of its file, however many objects share it (plan 6.7): five instances of a class with a reserved method name, reporting it once on load, once more after the file changes, and not at all when an unchanged file reloads; and a save that breaks the file is reported once, not by each (plan 6.10).", "linecount": 4 } }, @@ -447,6 +447,157 @@ "id": "obj-24", "maxclass": "newobj", "numinlets": 1, + "numoutlets": 5, + "outlettype": [ + "", + "", + "", + "", + "" + ], + "patching_rect": [ + 1020.0, + 320.0, + 163.0, + 22.0 + ], + "text": "regexp Failed.to.load" + } + }, + { + "box": { + "id": "obj-25", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 350.0, + 40.0, + 22.0 + ], + "text": "t b" + } + }, + { + "box": { + "id": "obj-26", + "maxclass": "newobj", + "numinlets": 3, + "numoutlets": 4, + "outlettype": [ + "", + "", + "", + "" + ], + "patching_rect": [ + 1020.0, + 380.0, + 135.0, + 22.0 + ], + "text": "counter 1 1000000" + } + }, + { + "box": { + "id": "obj-27", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 270.0, + 260.0, + 184.0, + 22.0 + ], + "text": "corrupt maxtest_reserved" + } + }, + { + "box": { + "id": "obj-28", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 410.0, + 40.0, + 22.0 + ], + "text": "i" + } + }, + { + "box": { + "id": "obj-29", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 440.0, + 44.0, + 22.0 + ], + "text": "== 1" + } + }, + { + "box": { + "id": "obj-30", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 110.0, + 394.0, + 22.0 + ], + "text": "test.assert broken-save-reported-once-for-five-objects" + } + }, + { + "box": { + "id": "obj-31", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 270.0, + 290.0, + 184.0, + 22.0 + ], + "text": "restore maxtest_reserved" + } + }, + { + "box": { + "id": "obj-32", + "maxclass": "newobj", + "numinlets": 1, "numoutlets": 0, "outlettype": [], "patching_rect": [ @@ -460,7 +611,7 @@ }, { "box": { - "id": "obj-25", + "id": "obj-33", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -469,7 +620,7 @@ ], "patching_rect": [ 1020.0, - 320.0, + 470.0, 72.0, 22.0 ], @@ -478,7 +629,7 @@ }, { "box": { - "id": "obj-26", + "id": "obj-34", "maxclass": "newobj", "numinlets": 1, "numoutlets": 5, @@ -491,7 +642,7 @@ ], "patching_rect": [ 1020.0, - 350.0, + 500.0, 177.0, 22.0 ], @@ -500,7 +651,7 @@ }, { "box": { - "id": "obj-27", + "id": "obj-35", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -509,7 +660,7 @@ ], "patching_rect": [ 1020.0, - 380.0, + 530.0, 86.0, 22.0 ], @@ -518,7 +669,7 @@ }, { "box": { - "id": "obj-28", + "id": "obj-36", "maxclass": "newobj", "numinlets": 1, "numoutlets": 2, @@ -528,7 +679,7 @@ ], "patching_rect": [ 1020.0, - 410.0, + 560.0, 51.0, 22.0 ], @@ -537,7 +688,7 @@ }, { "box": { - "id": "obj-29", + "id": "obj-37", "maxclass": "newobj", "numinlets": 3, "numoutlets": 4, @@ -549,7 +700,7 @@ ], "patching_rect": [ 1020.0, - 440.0, + 590.0, 135.0, 22.0 ], @@ -558,7 +709,7 @@ }, { "box": { - "id": "obj-30", + "id": "obj-38", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -567,7 +718,7 @@ ], "patching_rect": [ 1020.0, - 470.0, + 620.0, 51.0, 22.0 ], @@ -576,7 +727,7 @@ }, { "box": { - "id": "obj-31", + "id": "obj-39", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -585,7 +736,7 @@ ], "patching_rect": [ 1020.0, - 500.0, + 650.0, 72.0, 22.0 ], @@ -594,14 +745,14 @@ }, { "box": { - "id": "obj-32", + "id": "obj-40", "maxclass": "newobj", "numinlets": 1, "numoutlets": 0, "outlettype": [], "patching_rect": [ 1020.0, - 530.0, + 680.0, 170.0, 22.0 ], @@ -610,7 +761,7 @@ }, { "box": { - "id": "obj-33", + "id": "obj-41", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -628,7 +779,7 @@ }, { "box": { - "id": "obj-34", + "id": "obj-42", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -646,7 +797,7 @@ }, { "box": { - "id": "obj-35", + "id": "obj-43", "maxclass": "newobj", "numinlets": 1, "numoutlets": 5, @@ -668,7 +819,7 @@ }, { "box": { - "id": "obj-36", + "id": "obj-44", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -686,7 +837,7 @@ }, { "box": { - "id": "obj-37", + "id": "obj-45", "maxclass": "newobj", "numinlets": 1, "numoutlets": 2, @@ -705,7 +856,7 @@ }, { "box": { - "id": "obj-38", + "id": "obj-46", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -723,7 +874,7 @@ }, { "box": { - "id": "obj-39", + "id": "obj-47", "maxclass": "newobj", "numinlets": 1, "numoutlets": 3, @@ -743,7 +894,7 @@ }, { "box": { - "id": "obj-40", + "id": "obj-48", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -761,7 +912,7 @@ }, { "box": { - "id": "obj-41", + "id": "obj-49", "maxclass": "newobj", "numinlets": 1, "numoutlets": 2, @@ -780,7 +931,7 @@ }, { "box": { - "id": "obj-42", + "id": "obj-50", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -798,7 +949,7 @@ }, { "box": { - "id": "obj-43", + "id": "obj-51", "maxclass": "newobj", "numinlets": 1, "numoutlets": 2, @@ -817,7 +968,7 @@ }, { "box": { - "id": "obj-44", + "id": "obj-52", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -835,7 +986,7 @@ }, { "box": { - "id": "obj-45", + "id": "obj-53", "maxclass": "newobj", "numinlets": 1, "numoutlets": 2, @@ -854,7 +1005,7 @@ }, { "box": { - "id": "obj-46", + "id": "obj-54", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -867,12 +1018,12 @@ 79.0, 22.0 ], - "text": "delay 500" + "text": "delay 150" } }, { "box": { - "id": "obj-47", + "id": "obj-55", "maxclass": "newobj", "numinlets": 1, "numoutlets": 2, @@ -886,19 +1037,310 @@ 51.0, 22.0 ], - "text": "t b b" + "text": "t b b" + } + }, + { + "box": { + "id": "obj-56", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 588.0, + 86.0, + 22.0 + ], + "text": "delay 2500" + } + }, + { + "box": { + "id": "obj-57", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 618.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-58", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 648.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-59", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 678.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-60", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 708.0, + 79.0, + 22.0 + ], + "text": "delay 500" + } + }, + { + "box": { + "id": "obj-61", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 738.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + } + ], + "lines": [ + { + "patchline": { + "source": [ + "obj-4", + 0 + ], + "destination": [ + "obj-5", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-5", + 2 + ], + "destination": [ + "obj-6", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-6", + 0 + ], + "destination": [ + "obj-7", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-8", + 0 + ], + "destination": [ + "obj-2", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-9", + 0 + ], + "destination": [ + "obj-2", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-10", + 0 + ], + "destination": [ + "obj-2", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-11", + 0 + ], + "destination": [ + "obj-2", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-7", + 0 + ], + "destination": [ + "obj-12", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-12", + 0 + ], + "destination": [ + "obj-13", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-13", + 0 + ], + "destination": [ + "obj-14", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-15", + 0 + ], + "destination": [ + "obj-3", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-16", + 0 + ], + "destination": [ + "obj-2", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-7", + 0 + ], + "destination": [ + "obj-17", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-17", + 0 + ], + "destination": [ + "obj-18", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-18", + 0 + ], + "destination": [ + "obj-19", + 0 + ] } - } - ], - "lines": [ + }, { "patchline": { "source": [ - "obj-4", + "obj-20", 0 ], "destination": [ - "obj-5", + "obj-2", 0 ] } @@ -906,23 +1348,23 @@ { "patchline": { "source": [ - "obj-5", - 2 + "obj-7", + 0 ], "destination": [ - "obj-6", - 0 + "obj-21", + 1 ] } }, { "patchline": { "source": [ - "obj-6", + "obj-21", 0 ], "destination": [ - "obj-7", + "obj-22", 0 ] } @@ -930,11 +1372,11 @@ { "patchline": { "source": [ - "obj-8", + "obj-22", 0 ], "destination": [ - "obj-2", + "obj-23", 0 ] } @@ -942,11 +1384,11 @@ { "patchline": { "source": [ - "obj-9", + "obj-4", 0 ], "destination": [ - "obj-2", + "obj-24", 0 ] } @@ -954,11 +1396,23 @@ { "patchline": { "source": [ - "obj-10", + "obj-24", + 2 + ], + "destination": [ + "obj-25", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-25", 0 ], "destination": [ - "obj-2", + "obj-26", 0 ] } @@ -966,11 +1420,11 @@ { "patchline": { "source": [ - "obj-11", + "obj-27", 0 ], "destination": [ - "obj-2", + "obj-3", 0 ] } @@ -978,11 +1432,11 @@ { "patchline": { "source": [ - "obj-7", + "obj-26", 0 ], "destination": [ - "obj-12", + "obj-28", 1 ] } @@ -990,11 +1444,11 @@ { "patchline": { "source": [ - "obj-12", + "obj-28", 0 ], "destination": [ - "obj-13", + "obj-29", 0 ] } @@ -1002,11 +1456,11 @@ { "patchline": { "source": [ - "obj-13", + "obj-29", 0 ], "destination": [ - "obj-14", + "obj-30", 0 ] } @@ -1014,7 +1468,7 @@ { "patchline": { "source": [ - "obj-15", + "obj-31", 0 ], "destination": [ @@ -1026,11 +1480,11 @@ { "patchline": { "source": [ - "obj-16", + "obj-4", 0 ], "destination": [ - "obj-2", + "obj-33", 0 ] } @@ -1038,23 +1492,23 @@ { "patchline": { "source": [ - "obj-7", + "obj-33", 0 ], "destination": [ - "obj-17", - 1 + "obj-34", + 0 ] } }, { "patchline": { "source": [ - "obj-17", + "obj-34", 0 ], "destination": [ - "obj-18", + "obj-35", 0 ] } @@ -1062,11 +1516,11 @@ { "patchline": { "source": [ - "obj-18", - 0 + "obj-34", + 3 ], "destination": [ - "obj-19", + "obj-35", 0 ] } @@ -1074,11 +1528,11 @@ { "patchline": { "source": [ - "obj-20", + "obj-35", 0 ], "destination": [ - "obj-2", + "obj-36", 0 ] } @@ -1086,23 +1540,23 @@ { "patchline": { "source": [ - "obj-7", - 0 + "obj-36", + 1 ], "destination": [ - "obj-21", - 1 + "obj-37", + 0 ] } }, { "patchline": { "source": [ - "obj-21", + "obj-37", 0 ], "destination": [ - "obj-22", + "obj-38", 0 ] } @@ -1110,11 +1564,11 @@ { "patchline": { "source": [ - "obj-22", + "obj-38", 0 ], "destination": [ - "obj-23", + "obj-39", 0 ] } @@ -1122,23 +1576,23 @@ { "patchline": { "source": [ - "obj-4", + "obj-36", 0 ], "destination": [ - "obj-25", - 0 + "obj-39", + 1 ] } }, { "patchline": { "source": [ - "obj-25", + "obj-39", 0 ], "destination": [ - "obj-26", + "obj-40", 0 ] } @@ -1146,11 +1600,11 @@ { "patchline": { "source": [ - "obj-26", + "obj-41", 0 ], "destination": [ - "obj-27", + "obj-42", 0 ] } @@ -1158,11 +1612,11 @@ { "patchline": { "source": [ - "obj-26", - 3 + "obj-42", + 0 ], "destination": [ - "obj-27", + "obj-43", 0 ] } @@ -1170,11 +1624,11 @@ { "patchline": { "source": [ - "obj-27", - 0 + "obj-43", + 4 ], "destination": [ - "obj-28", + "obj-8", 0 ] } @@ -1182,11 +1636,11 @@ { "patchline": { "source": [ - "obj-28", - 1 + "obj-43", + 3 ], "destination": [ - "obj-29", + "obj-9", 0 ] } @@ -1194,11 +1648,23 @@ { "patchline": { "source": [ - "obj-29", + "obj-43", + 2 + ], + "destination": [ + "obj-10", 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-43", + 1 ], "destination": [ - "obj-30", + "obj-11", 0 ] } @@ -1206,11 +1672,11 @@ { "patchline": { "source": [ - "obj-30", + "obj-43", 0 ], "destination": [ - "obj-31", + "obj-44", 0 ] } @@ -1218,23 +1684,23 @@ { "patchline": { "source": [ - "obj-28", + "obj-44", 0 ], "destination": [ - "obj-31", - 1 + "obj-45", + 0 ] } }, { "patchline": { "source": [ - "obj-31", - 0 + "obj-45", + 1 ], "destination": [ - "obj-32", + "obj-12", 0 ] } @@ -1242,11 +1708,11 @@ { "patchline": { "source": [ - "obj-33", + "obj-45", 0 ], "destination": [ - "obj-34", + "obj-46", 0 ] } @@ -1254,11 +1720,11 @@ { "patchline": { "source": [ - "obj-34", + "obj-46", 0 ], "destination": [ - "obj-35", + "obj-47", 0 ] } @@ -1266,11 +1732,11 @@ { "patchline": { "source": [ - "obj-35", - 4 + "obj-47", + 2 ], "destination": [ - "obj-8", + "obj-15", 0 ] } @@ -1278,11 +1744,11 @@ { "patchline": { "source": [ - "obj-35", - 3 + "obj-47", + 1 ], "destination": [ - "obj-9", + "obj-16", 0 ] } @@ -1290,11 +1756,11 @@ { "patchline": { "source": [ - "obj-35", - 2 + "obj-47", + 0 ], "destination": [ - "obj-10", + "obj-48", 0 ] } @@ -1302,11 +1768,11 @@ { "patchline": { "source": [ - "obj-35", - 1 + "obj-48", + 0 ], "destination": [ - "obj-11", + "obj-49", 0 ] } @@ -1314,11 +1780,11 @@ { "patchline": { "source": [ - "obj-35", - 0 + "obj-49", + 1 ], "destination": [ - "obj-36", + "obj-17", 0 ] } @@ -1326,11 +1792,11 @@ { "patchline": { "source": [ - "obj-36", + "obj-49", 0 ], "destination": [ - "obj-37", + "obj-50", 0 ] } @@ -1338,11 +1804,11 @@ { "patchline": { "source": [ - "obj-37", - 1 + "obj-50", + 0 ], "destination": [ - "obj-12", + "obj-51", 0 ] } @@ -1350,11 +1816,11 @@ { "patchline": { "source": [ - "obj-37", - 0 + "obj-51", + 1 ], "destination": [ - "obj-38", + "obj-20", 0 ] } @@ -1362,11 +1828,11 @@ { "patchline": { "source": [ - "obj-38", + "obj-51", 0 ], "destination": [ - "obj-39", + "obj-52", 0 ] } @@ -1374,11 +1840,11 @@ { "patchline": { "source": [ - "obj-39", - 2 + "obj-52", + 0 ], "destination": [ - "obj-15", + "obj-53", 0 ] } @@ -1386,11 +1852,11 @@ { "patchline": { "source": [ - "obj-39", + "obj-53", 1 ], "destination": [ - "obj-16", + "obj-21", 0 ] } @@ -1398,11 +1864,11 @@ { "patchline": { "source": [ - "obj-39", + "obj-53", 0 ], "destination": [ - "obj-40", + "obj-54", 0 ] } @@ -1410,11 +1876,11 @@ { "patchline": { "source": [ - "obj-40", + "obj-54", 0 ], "destination": [ - "obj-41", + "obj-55", 0 ] } @@ -1422,11 +1888,11 @@ { "patchline": { "source": [ - "obj-41", + "obj-55", 1 ], "destination": [ - "obj-17", + "obj-27", 0 ] } @@ -1434,11 +1900,11 @@ { "patchline": { "source": [ - "obj-41", + "obj-55", 0 ], "destination": [ - "obj-42", + "obj-56", 0 ] } @@ -1446,11 +1912,11 @@ { "patchline": { "source": [ - "obj-42", + "obj-56", 0 ], "destination": [ - "obj-43", + "obj-57", 0 ] } @@ -1458,11 +1924,11 @@ { "patchline": { "source": [ - "obj-43", + "obj-57", 1 ], "destination": [ - "obj-20", + "obj-28", 0 ] } @@ -1470,11 +1936,11 @@ { "patchline": { "source": [ - "obj-43", + "obj-57", 0 ], "destination": [ - "obj-44", + "obj-58", 0 ] } @@ -1482,11 +1948,11 @@ { "patchline": { "source": [ - "obj-44", + "obj-58", 0 ], "destination": [ - "obj-45", + "obj-59", 0 ] } @@ -1494,11 +1960,11 @@ { "patchline": { "source": [ - "obj-45", + "obj-59", 1 ], "destination": [ - "obj-21", + "obj-31", 0 ] } @@ -1506,11 +1972,11 @@ { "patchline": { "source": [ - "obj-45", + "obj-59", 0 ], "destination": [ - "obj-46", + "obj-60", 0 ] } @@ -1518,11 +1984,11 @@ { "patchline": { "source": [ - "obj-46", + "obj-60", 0 ], "destination": [ - "obj-47", + "obj-61", 0 ] } @@ -1530,11 +1996,11 @@ { "patchline": { "source": [ - "obj-47", + "obj-61", 1 ], "destination": [ - "obj-24", + "obj-32", 0 ] } diff --git a/runtime-tests/run.py b/runtime-tests/run.py index e493cbf..5578a7c 100644 --- a/runtime-tests/run.py +++ b/runtime-tests/run.py @@ -357,6 +357,12 @@ def check_prerequisites(max_app: Path, packages: Path) -> None: if not EXTERNAL.exists(): raise RunError("the external is not built — cmake -S . -B build && cmake --build build" if PACKAGE == ROOT else f"no external in {PACKAGE}") + binary = EXTERNAL / "Contents" / "MacOS" / "tap.python~" + sources = [f for folder in ("core/include", "source/projects") for f in (ROOT / folder).rglob("*") if f.is_file()] + newest = max(sources, key=lambda f: f.stat().st_mtime) + built_here = EXTERNAL.resolve().is_relative_to(ROOT) # not an installed release's + if built_here and binary.exists() and newest.stat().st_mtime > binary.stat().st_mtime: # after switching branches + raise RunError(f"the external is older than {newest.relative_to(ROOT)} — cmake --build build") if not SUPPORT.exists(): raise RunError(f"no runtime in {SUPPORT} — run scripts/install-runtime.sh") if not packages.is_dir(): From 3a91cb3a795ae6d2cfc21263a7aa6c1023ed0ff4 Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Wed, 30 Sep 2026 09:58:49 -0500 Subject: [PATCH 04/15] 2.4 (a): process() with several inputs and outputs, in the core MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- core/include/tap/python/processor.h | 371 +++++++++++++----- core/include/tap/python/runtime.h | 31 +- core/tests/CMakeLists.txt | 1 + core/tests/python/block_two_by_two.py | 7 + core/tests/python/generator.py | 10 + core/tests/python/mixed_inputs.py | 7 + core/tests/python/star_inputs.py | 6 + core/tests/python/tuple_return.py | 2 +- core/tests/python/two_by_two.py | 6 + core/tests/python/two_inputs.py | 4 +- core/tests/python/wrong_count.py | 6 + core/tests/test_channels.cpp | 178 +++++++++ core/tests/test_processor.cpp | 18 +- docs/PRODUCTION-PLAN.md | 14 +- .../tap.python_tilde/tap.python_tilde.h | 9 +- 15 files changed, 540 insertions(+), 130 deletions(-) create mode 100644 core/tests/python/block_two_by_two.py create mode 100644 core/tests/python/generator.py create mode 100644 core/tests/python/mixed_inputs.py create mode 100644 core/tests/python/star_inputs.py create mode 100644 core/tests/python/two_by_two.py create mode 100644 core/tests/python/wrong_count.py create mode 100644 core/tests/test_channels.cpp diff --git a/core/include/tap/python/processor.h b/core/include/tap/python/processor.h index 75eae34..91f885a 100644 --- a/core/include/tap/python/processor.h +++ b/core/include/tap/python/processor.h @@ -8,8 +8,11 @@ // it to the host: // - the class's type-annotated public fields become attributes (attributes()) // - its public methods become messages, their argument types taken from the hints (messages()) -// - a method `process()` becomes the audio callback (process()): `process(self, x: float) -> float` -// is called once per sample; `process(self, x: np.ndarray) -> np.ndarray` once per vector +// - a method `process()` becomes the audio callback (process()): its parameters are the signal +// inputs and its return the outputs — `process(self, x: float) -> float` is called once per +// sample, `process(self, x: np.ndarray) -> np.ndarray` once per vector, and +// `process(self, a: float, b: float) -> tuple[float, float]` takes two inputs and gives two +// outputs (plan 2.4); input_count() and output_count() tell the host how many // - an optional `prepare(self, sample_rate: float, vector_size: int)` is told the audio settings // (prepare()) before the instance first processes audio, and again whenever they change // @@ -113,6 +116,16 @@ namespace tap::python { /// called per sample. Main thread, after load(). bool block_mode() const noexcept { return m_block_mode; } + /// How many signal inputs and outputs the class's process() declares — its parameters, and + /// the values its return hint names (one, or n for tuple[...]) — for the host to give the + /// object that many. 1 and 1 until a class binds process(); unchanged by a failed load. + /// Main thread, after load(). + std::size_t input_count() const noexcept { return m_inputs; } + std::size_t output_count() const noexcept { return m_outputs; } + + /// The most inputs, and the most outputs, a process() may declare. + static constexpr std::size_t k_max_channels = 64; + /// Load `/.py` (executing it only if its source changed since any /// processor last loaded it), instantiate the class, carry the previous instance's /// attribute values over, and rebuild the attribute and message descriptions. Returns true @@ -199,7 +212,7 @@ namespace tap::python { // Tell the new instance the audio settings before anything can run it. if (m_prepared) { if (next.block_mode) { - ensure_block_buffer(m_vector_size); + ensure_block_buffers(m_vector_size, next.inputs); } call_prepare(next.prepare_function); } @@ -211,6 +224,8 @@ namespace tap::python { previous.process_function = m_process_function.exchange(next.process_function); previous.prepare_function = std::exchange(m_prepare_function, next.prepare_function); previous.block_mode = std::exchange(m_block_mode, next.block_mode); + m_inputs = next.inputs; + m_outputs = next.outputs; previous.attributes = std::exchange(m_attributes, std::move(next.attributes)); previous.messages = std::exchange(m_messages, std::move(next.messages)); next.instance = nullptr; @@ -238,7 +253,7 @@ namespace tap::python { gil_lock lock; if (m_block_mode) { - ensure_block_buffer(vector_size); + ensure_block_buffers(vector_size, m_inputs); } PyObject* function = m_prepare_function; // bound to the current instance Py_XINCREF(function); @@ -271,6 +286,11 @@ namespace tap::python { "process() produced a non-finite sample (NaN or infinity) — replaced with 0.0 (reported once per " "load)"); } + if (const auto returned = m_pending_bad_count.exchange(k_no_length); returned != k_no_length) { + log(log_level::error, "process() returned " + std::to_string(returned) + " value(s) for " + + std::to_string(m_bad_count_expected.load()) + + " outputs — output as silence (reported once per load)"); + } if (const auto returned = m_pending_bad_length.exchange(k_no_length); returned != k_no_length) { log(log_level::error, "process() returned " + std::to_string(returned) + " sample(s) for a vector of " + std::to_string(m_bad_length_expected.load()) @@ -425,41 +445,52 @@ namespace tap::python { return true; } - /// The audio callback. Calls the class's process() once per sample, or once per vector when - /// its input is hinted np.ndarray. `input` and `output` may alias. Outputs silence while + /// The audio callback: `input_count` input channels and `output_count` output channels of + /// `frame_count` samples. Calls the class's process() once per sample, or once per vector + /// when its inputs are hinted np.ndarray, with as many inputs as it declares: an input the + /// host does not give reads as silence, and an output it does not give is dropped; an output + /// the class does not give is silent. Channels may alias (in place). Outputs silence while /// not bound; if process() raises, silences the rest of the vector, unbinds until the next /// load() and records the exception for flush_reports(). A reload landing mid-vector does /// not affect this vector: it finishes on the binding it started with. - void process(const double* input, double* output, const std::size_t frame_count) { + void process(const double* const* inputs, const std::size_t input_count, double* const* outputs, + const std::size_t output_count, const std::size_t frame_count) { if (!has_process()) { - std::fill(output, output + frame_count, 0.0); + silence(outputs, 0, output_count, 0, frame_count); return; } gil_lock lock; - // the instance and function are swapped together, with no Python call between, so - // under the GIL they are always a matching pair + // the instance, function and channel counts are swapped together, with no Python call + // between, so under the GIL they always match PyObject* function = m_process_function.load(); PyObject* instance = m_instance.load(); if (!function || !instance) { - std::fill(output, output + frame_count, 0.0); + silence(outputs, 0, output_count, 0, frame_count); return; } Py_INCREF(function); Py_INCREF(instance); + const channels io{inputs, input_count, outputs, output_count, m_inputs, m_outputs}; if (m_block_mode) { - process_block(function, instance, input, output, frame_count); + process_block(function, instance, io, frame_count); } else { - process_samples(function, instance, input, output, frame_count); + process_samples(function, instance, io, frame_count); } + silence(outputs, io.outputs, output_count, 0, frame_count); // outputs the class does not give Py_DECREF(instance); Py_DECREF(function); } + /// One input and one output: process(&input, 1, &output, 1, frame_count). + void process(const double* input, double* output, const std::size_t frame_count) { + process(&input, 1, &output, 1, frame_count); + } + private: struct bound_message { message_info info; @@ -472,6 +503,8 @@ namespace tap::python { PyObject* process_function{}; // strong PyObject* prepare_function{}; // strong, or null bool block_mode{}; // process() takes and returns np.ndarray + std::size_t inputs{1}; // the signal inputs process() declares + std::size_t outputs{1}; // and the outputs std::vector attributes; std::vector messages; }; @@ -491,11 +524,18 @@ namespace tap::python { // The rest of the binding and the block buffer: read and written only under the GIL. PyObject* m_prepare_function{}; // strong, or null bool m_block_mode{}; - bool m_announcing{}; // this load() ran the file: see announce() - PyObject* m_block_input{}; // strong: the np.ndarray process() receives, reused every vector - Py_buffer m_block_view{}; // held while m_block_input is, so its memory cannot move - double* m_block_data{}; - std::size_t m_block_size{}; + std::size_t m_inputs{1}; // the bound process()'s inputs and outputs + std::size_t m_outputs{1}; + bool m_announcing{}; // this load() ran the file: see announce() + // The np.ndarray each input arrives in, reused every vector: strong, its buffer held so its + // memory cannot move. + struct block_buffer { + PyObject* array{}; + Py_buffer view{}; + double* data{}; + }; + std::vector m_block_inputs; + std::size_t m_block_size{}; // Attribute values captured from the previous instance, for the next one (main thread). struct carried_value { attribute_info info; @@ -517,6 +557,9 @@ namespace tap::python { std::atomic m_warned_non_numeric{}; std::atomic m_warned_non_finite{}; std::atomic m_warned_bad_length{}; + std::atomic m_pending_bad_count{k_no_length}; + std::atomic m_bad_count_expected{}; + std::atomic m_warned_bad_count{}; void log(const log_level level, const std::string& text) const { if (m_log) { @@ -708,6 +751,7 @@ namespace tap::python { m_warned_non_numeric = false; m_warned_non_finite = false; m_warned_bad_length = false; + m_warned_bad_count = false; } void notify_report() const { @@ -738,6 +782,18 @@ namespace tap::python { notify_report(); } + /// Record that process() returned `result` when it declares `outputs` outputs: not a tuple of + /// that many values. Caller holds the GIL. + void record_bad_count(PyObject* result, const std::size_t outputs) { + if (m_warned_bad_count.exchange(true)) { + return; + } + const auto count = PyTuple_Check(result) ? static_cast(PyTuple_GET_SIZE(result)) : 1; + m_bad_count_expected = static_cast(outputs); + m_pending_bad_count = count; + notify_report(); + } + /// Replace non-finite samples with 0.0, recording the first occurrence per load. void sanitize(double* output, const std::size_t frame_count) { bool found = false; @@ -753,66 +809,145 @@ namespace tap::python { } } - /// The per-sample path. Caller holds the GIL and references to `function` and `instance`. - void process_samples(PyObject* function, PyObject* instance, const double* input, double* output, + /// The host's channels, and how many process() declares. Main thread and audio thread. + struct channels { + const double* const* in; // the host's input channels + std::size_t host_inputs; // how many it gives + double* const* out; // the host's output channels + std::size_t host_outputs; // how many it gives + std::size_t inputs; // how many process() declares + std::size_t outputs; + }; + + /// Zero channels [first, end) of `out`, from `first_frame` to `frame_count`. + static void silence(double* const* out, const std::size_t first, const std::size_t end, + const std::size_t first_frame, const std::size_t frame_count) { + for (std::size_t c = first; c < end; ++c) { + std::fill(out[c] + first_frame, out[c] + frame_count, 0.0); + } + } + + /// The per-sample path: process(x0, x1, ...) per sample, returning a number, or a tuple of + /// as many numbers as it declares outputs. Caller holds the GIL and references to + /// `function` and `instance`. + void process_samples(PyObject* function, PyObject* instance, const channels& io, const std::size_t frame_count) { + const std::size_t written = std::min(io.outputs, io.host_outputs); + PyObject* call_args[1 + k_max_channels]{instance}; for (std::size_t i = 0; i < frame_count; ++i) { - PyObject* x = PyFloat_FromDouble(input[i]); - if (!x) { - record_exception(); - std::fill(output + i, output + frame_count, 0.0); - return; + // every input of this sample is read before any output of it is written (in place) + for (std::size_t c = 0; c < io.inputs; ++c) { + call_args[1 + c] = PyFloat_FromDouble(c < io.host_inputs ? io.in[c][i] : 0.0); + if (!call_args[1 + c]) { + release_arguments(call_args, c); + record_exception(); + silence(io.out, 0, written, i, frame_count); + return; + } } - PyObject* const call_args[2] = {instance, x}; - PyObject* result = PyObject_Vectorcall(function, call_args, 2, nullptr); - Py_DECREF(x); + PyObject* result = PyObject_Vectorcall(function, call_args, 1 + io.inputs, nullptr); + release_arguments(call_args, io.inputs); if (!result) { record_exception(); unbind_process(function); // load() re-arms it - std::fill(output + i, output + frame_count, 0.0); + silence(io.out, 0, written, i, frame_count); return; } - - double y = PyFloat_AsDouble(result); // also handles ints and other number types - if (y == -1.0 && PyErr_Occurred()) { - PyErr_Clear(); - record_non_numeric(result); - y = 0.0; + if (io.outputs == 1) { + if (written == 1) { + io.out[0][i] = to_sample(result); + } + } + else if (PyTuple_Check(result) && static_cast(PyTuple_GET_SIZE(result)) == io.outputs) { + for (std::size_t c = 0; c < written; ++c) { + io.out[c][i] = to_sample(PyTuple_GET_ITEM(result, static_cast(c))); + } + } + else { + record_bad_count(result, io.outputs); + for (std::size_t c = 0; c < written; ++c) { + io.out[c][i] = 0.0; + } } - output[i] = y; Py_DECREF(result); } - sanitize(output, frame_count); + for (std::size_t c = 0; c < written; ++c) { + sanitize(io.out[c], frame_count); + } + } + + /// Release the `count` input values after `call_args[0]`. + static void release_arguments(PyObject* const* call_args, const std::size_t count) { + for (std::size_t c = 0; c < count; ++c) { + Py_DECREF(call_args[1 + c]); + } + } + + /// A sample from what process() returned: any number (ints too); anything else is 0.0, + /// reported once per load. + double to_sample(PyObject* value) { + const double y = PyFloat_AsDouble(value); + if (y == -1.0 && PyErr_Occurred()) { + PyErr_Clear(); + record_non_numeric(value); + return 0.0; + } + return y; } - /// The block path: one call per vector with the reused input array. Caller holds the GIL - /// and references to `function` and `instance`. - void process_block(PyObject* function, PyObject* instance, const double* input, double* output, - const std::size_t frame_count) { + /// The block path: one call per vector with the reused input arrays, returning an array, or + /// a tuple of as many arrays as it declares outputs. Caller holds the GIL and references to + /// `function` and `instance`. + void process_block(PyObject* function, PyObject* instance, const channels& io, const std::size_t frame_count) { + const std::size_t written = std::min(io.outputs, io.host_outputs); // allocates only when the vector size differs from the one prepare() announced - if (!ensure_block_buffer(frame_count)) { - std::fill(output, output + frame_count, 0.0); + if (!ensure_block_buffers(frame_count, io.inputs)) { + silence(io.out, 0, written, 0, frame_count); return; } - // copy in and take our reference before calling, which may yield the GIL - std::memcpy(m_block_data, input, frame_count * sizeof(double)); - PyObject* x = m_block_input; - Py_INCREF(x); - PyObject* const call_args[2] = {instance, x}; - PyObject* result = PyObject_Vectorcall(function, call_args, 2, nullptr); - Py_DECREF(x); + // copy in and take our references before calling, which may yield the GIL (and a reload + // may replace the arrays meanwhile) + PyObject* call_args[1 + k_max_channels]{instance}; + for (std::size_t c = 0; c < io.inputs; ++c) { + auto& buffer = m_block_inputs[c]; + if (c < io.host_inputs) { + std::memcpy(buffer.data, io.in[c], frame_count * sizeof(double)); + } + else { + std::fill(buffer.data, buffer.data + frame_count, 0.0); + } + call_args[1 + c] = buffer.array; + Py_INCREF(buffer.array); + } + PyObject* result = PyObject_Vectorcall(function, call_args, 1 + io.inputs, nullptr); + release_arguments(call_args, io.inputs); if (!result) { record_exception(); unbind_process(function); - std::fill(output, output + frame_count, 0.0); + silence(io.out, 0, written, 0, frame_count); return; } - copy_block_result(result, output, frame_count); + if (io.outputs == 1) { + if (written == 1) { + copy_block_result(result, io.out[0], frame_count); + } + } + else if (PyTuple_Check(result) && static_cast(PyTuple_GET_SIZE(result)) == io.outputs) { + for (std::size_t c = 0; c < written; ++c) { + copy_block_result(PyTuple_GET_ITEM(result, static_cast(c)), io.out[c], frame_count); + } + } + else { + record_bad_count(result, io.outputs); + silence(io.out, 0, written, 0, frame_count); + } Py_DECREF(result); - sanitize(output, frame_count); + for (std::size_t c = 0; c < written; ++c) { + sanitize(io.out[c], frame_count); + } } static bool is_native_double(const Py_buffer& view) { @@ -882,54 +1017,64 @@ namespace tap::python { Py_DECREF(converted); } - /// Make sure the block input array holds `size` samples, building a new np.zeros(size) if - /// not. Caller holds the GIL. The new array is built completely, then swapped in with no - /// Python call in between (building it can yield the GIL). Returns false if numpy failed. - bool ensure_block_buffer(const std::size_t size) { - if (m_block_input && m_block_size == size) { + /// Make sure there are at least `count` block input arrays of `size` samples, building a new + /// set of np.zeros(size) if not. Caller holds the GIL. The new set is built completely, then + /// swapped in with no Python call in between (building it can yield the GIL); it never + /// shrinks, so a process() still running on a binding with more inputs finds enough. + /// Returns false if numpy failed. + bool ensure_block_buffers(const std::size_t size, const std::size_t count) { + if (m_block_size == size && m_block_inputs.size() >= count) { return true; } - - PyObject* array = nullptr; - if (PyObject* numpy = PyImport_ImportModule("numpy")) { - array = PyObject_CallMethod(numpy, "zeros", "n", static_cast(size)); - Py_DECREF(numpy); - } - Py_buffer view; - if (!array || PyObject_GetBuffer(array, &view, PyBUF_WRITABLE | PyBUF_C_CONTIGUOUS | PyBUF_FORMAT) != 0) { - PyErr_Clear(); - Py_XDECREF(array); - return false; + const auto wanted = std::max(count, m_block_size == size ? m_block_inputs.size() : std::size_t{0}); + + std::vector arrays; + arrays.reserve(wanted); + PyObject* numpy = PyImport_ImportModule("numpy"); + for (std::size_t c = 0; numpy && c < wanted; ++c) { + PyObject* array = PyObject_CallMethod(numpy, "zeros", "n", static_cast(size)); + Py_buffer view; + if (!array + || PyObject_GetBuffer(array, &view, PyBUF_WRITABLE | PyBUF_C_CONTIGUOUS | PyBUF_FORMAT) != 0) { + Py_XDECREF(array); + break; + } + if (!is_native_double(view)) { + PyBuffer_Release(&view); + Py_DECREF(array); + break; + } + arrays.push_back({array, view, static_cast(view.buf)}); } - if (!is_native_double(view)) { - PyBuffer_Release(&view); - Py_DECREF(array); + Py_XDECREF(numpy); + PyErr_Clear(); + if (arrays.size() != wanted) { + release(arrays); return false; } - if (m_block_input && m_block_size == size) { // another thread built one meanwhile - PyBuffer_Release(&view); - Py_DECREF(array); + if (m_block_size == size && m_block_inputs.size() >= count) { // another thread built a set meanwhile + release(arrays); return true; } - PyObject* old_input = std::exchange(m_block_input, array); - Py_buffer old_view = std::exchange(m_block_view, view); - m_block_data = static_cast(view.buf); - m_block_size = size; - if (old_input) { - PyBuffer_Release(&old_view); - Py_DECREF(old_input); - } + auto previous = std::exchange(m_block_inputs, std::move(arrays)); + m_block_size = size; + release(previous); return true; } /// Caller holds the GIL. - void release_block_buffer() { - if (m_block_input) { - PyBuffer_Release(&m_block_view); - Py_CLEAR(m_block_input); + static void release(std::vector& arrays) { + for (auto& buffer : arrays) { + PyBuffer_Release(&buffer.view); + Py_DECREF(buffer.array); } - m_block_data = nullptr; + arrays.clear(); + } + + /// Caller holds the GIL. + void release_block_buffer() { + release(m_block_inputs); m_block_size = 0; } @@ -1024,6 +1169,8 @@ namespace tap::python { struct signature { std::vector parameters; std::string return_kind; + int return_count{1}; // values the return hint names; -1: a tuple of unsaid length + std::string return_element_kind; // the value's hint kind, or a tuple's first element's }; // inspect.Parameter.kind values @@ -1044,6 +1191,8 @@ namespace tap::python { PyObject* parameters = PyTuple_GetItem(result, 0); // borrowed sig.return_kind = utf8(PyTuple_GetItem(result, 1)); report_hint_error(PyTuple_GetItem(result, 2), what); + sig.return_count = static_cast(PyLong_AsLong(PyTuple_GetItem(result, 3))); + sig.return_element_kind = utf8(PyTuple_GetItem(result, 4)); const Py_ssize_t count = parameters ? PyList_Size(parameters) : 0; for (Py_ssize_t i = 0; i < count; ++i) { @@ -1121,31 +1270,45 @@ namespace tap::python { "staticmethod); audio is not bound"); return; } - int in_count = 0; - bool block_input = false; + // 2.4: the positional parameters are the signal inputs, all per vector (np.ndarray) or all + // per sample; the return hint names the outputs — one value, or tuple[...] of n + std::size_t inputs = 0; + std::size_t per_vector = 0; + bool var_inputs = false; for (const auto& p : sig->parameters) { if (p.parameter_kind == k_positional_only || p.parameter_kind == k_positional_or_named) { - if (in_count == 0) { - block_input = p.kind == "ndarray"; - } - ++in_count; + ++inputs; + per_vector += p.kind == "ndarray" ? 1 : 0; } + var_inputs = var_inputs || p.parameter_kind == k_var_positional; } - - if (in_count > 1) { - announce(log_level::error, "process() declares " + std::to_string(in_count) - + " inputs but only the first is supported (single-channel object)"); - } - if (sig->return_kind == "tuple") { - announce( - log_level::error, - "process() returns a tuple — multichannel output is not supported yet; use a single float return"); + const auto fail = [&](const std::string& why) { + announce(log_level::error, "process() " + why + "; audio is not bound"); Py_DECREF(fn); - return; + }; + if (var_inputs) { + return fail("takes *args, but its parameters are the object's signal inputs: name each one"); + } + if (per_vector != 0 && per_vector != inputs) { + return fail("mixes np.ndarray inputs (per vector) with others (per sample): hint them all np.ndarray " + "or all float"); + } + if (sig->return_count < 1) { + return fail("returns a tuple without saying how many values: hint it tuple[float, float] (or " + "tuple[np.ndarray, np.ndarray]), one per output"); + } + const auto outputs = static_cast(sig->return_count); + if (inputs > k_max_channels || outputs > k_max_channels) { + return fail("declares " + std::to_string(inputs) + " inputs and " + std::to_string(outputs) + + " outputs; the most is " + std::to_string(k_max_channels) + " of each"); } + // with no inputs (a generator), the return hint says which path + const bool block_input = inputs != 0 ? per_vector == inputs : sig->return_element_kind == "ndarray"; b.process_function = fn; // takes the reference b.block_mode = block_input; // announced by load() once the binding is in place + b.inputs = inputs; + b.outputs = outputs; } /// Bind a public method as a message, described by its signature. A keyword-only parameter diff --git a/core/include/tap/python/runtime.h b/core/include/tap/python/runtime.h index b44a903..6cb924c 100644 --- a/core/include/tap/python/runtime.h +++ b/core/include/tap/python/runtime.h @@ -191,8 +191,11 @@ namespace tap::python { // staticmethods — found without running descriptors, so a property getter never runs just // because the class was loaded. Each callable is bound: call it with the arguments only. // - // describe(callable) -> ([(name, kind, parameter_kind, has_default)], return_kind, error). - // parameter_kind is inspect.Parameter.kind as an int. + // describe(callable) -> ([(name, kind, parameter_kind, has_default)], return_kind, error, + // return_count, return_element_kind). parameter_kind is inspect.Parameter.kind as an int. + // return_count is how many values a return hint declares: 1, or n for tuple[a, b, ...] (-1 + // when a tuple's length is not said: tuple, tuple[float, ...]); return_element_kind is the + // hint kind of the value, or of a tuple's first element. inline constexpr const char* k_support_source = R"( import inspect, re, sys, time, types, typing @@ -302,7 +305,29 @@ def describe(fn): p.default is not inspect.Parameter.empty) for p in inspect.signature(fn).parameters.values() ] - return parameters, hint_kind(hints.get('return', inspect.Parameter.empty)), error + returned = hints.get('return', inspect.Parameter.empty) + return (parameters, hint_kind(returned), error) + return_shape(returned) + +def return_shape(hint): + if hint is inspect.Parameter.empty: + return 1, 'any' + if isinstance(hint, str): + text = hint.strip() + for prefix in ('typing.Tuple[', 'Tuple[', 'tuple['): + if text.startswith(prefix) and text.endswith(']'): + parts = [p.strip() for p in text[len(prefix):-1].split(',')] + if '...' in parts or parts == ['']: + return -1, 'any' + return len(parts), hint_kind(parts[0]) + if text in ('tuple', 'Tuple', 'typing.Tuple'): + return -1, 'any' + return 1, hint_kind(hint) + if hint is tuple or typing.get_origin(hint) is tuple: + args = typing.get_args(hint) + if not args or Ellipsis in args or args == ((),): + return -1, 'any' + return len(args), hint_kind(args[0]) + return 1, hint_kind(hint) )"; /// Create the support module (initialize() calls this with the GIL held). diff --git a/core/tests/CMakeLists.txt b/core/tests/CMakeLists.txt index 9917eb3..30d74d4 100644 --- a/core/tests/CMakeLists.txt +++ b/core/tests/CMakeLists.txt @@ -34,6 +34,7 @@ add_executable(tap_python_core_tests test_realtime.cpp test_loading.cpp test_types.cpp + test_channels.cpp ) target_link_libraries(tap_python_core_tests PRIVATE tap::python Python3::Python Catch2::Catch2WithMain) diff --git a/core/tests/python/block_two_by_two.py b/core/tests/python/block_two_by_two.py new file mode 100644 index 0000000..4b7b058 --- /dev/null +++ b/core/tests/python/block_two_by_two.py @@ -0,0 +1,7 @@ +# Test fixture: two inputs and two outputs, per vector (plan 2.4). +import numpy as np + + +class block_two_by_two: + def process(self, a: np.ndarray, b: np.ndarray) -> tuple[np.ndarray, np.ndarray]: + return a + b, a - b diff --git a/core/tests/python/generator.py b/core/tests/python/generator.py new file mode 100644 index 0000000..1d3fcee --- /dev/null +++ b/core/tests/python/generator.py @@ -0,0 +1,10 @@ +# Test fixture: no inputs — a generator (plan 2.4): the sample count so far. + + +class generator: + def __init__(self): + self.count = 0 + + def process(self) -> float: + self.count += 1 + return float(self.count) diff --git a/core/tests/python/mixed_inputs.py b/core/tests/python/mixed_inputs.py new file mode 100644 index 0000000..babc5d9 --- /dev/null +++ b/core/tests/python/mixed_inputs.py @@ -0,0 +1,7 @@ +# Test fixture: one input per vector and one per sample, which cannot be bound (plan 2.4). +import numpy as np + + +class mixed_inputs: + def process(self, a: np.ndarray, b: float) -> np.ndarray: + return a diff --git a/core/tests/python/star_inputs.py b/core/tests/python/star_inputs.py new file mode 100644 index 0000000..407f4b0 --- /dev/null +++ b/core/tests/python/star_inputs.py @@ -0,0 +1,6 @@ +# Test fixture: process(*args), which cannot say how many inputs it has (plan 2.4). + + +class star_inputs: + def process(self, *xs: float) -> float: + return sum(xs) diff --git a/core/tests/python/tuple_return.py b/core/tests/python/tuple_return.py index d74f075..3552448 100644 --- a/core/tests/python/tuple_return.py +++ b/core/tests/python/tuple_return.py @@ -1,4 +1,4 @@ -# Test fixture: process() declares a tuple return, which is not supported yet. +# Test fixture: process() returns a tuple without saying how many values (plan 2.4). class tuple_return: diff --git a/core/tests/python/two_by_two.py b/core/tests/python/two_by_two.py new file mode 100644 index 0000000..c722162 --- /dev/null +++ b/core/tests/python/two_by_two.py @@ -0,0 +1,6 @@ +# Test fixture: two inputs and two outputs, per sample (plan 2.4). + + +class two_by_two: + def process(self, a: float, b: float) -> tuple[float, float]: + return a + b, a - b diff --git a/core/tests/python/two_inputs.py b/core/tests/python/two_inputs.py index ef353f6..c60615b 100644 --- a/core/tests/python/two_inputs.py +++ b/core/tests/python/two_inputs.py @@ -1,6 +1,6 @@ -# Test fixture: process() declares two inputs; only the first is supported. +# Test fixture: process() with two inputs and one output (plan 2.4). class two_inputs: def process(self, x: float, y: float) -> float: - return x + return x - y diff --git a/core/tests/python/wrong_count.py b/core/tests/python/wrong_count.py new file mode 100644 index 0000000..62d96f8 --- /dev/null +++ b/core/tests/python/wrong_count.py @@ -0,0 +1,6 @@ +# Test fixture: declares two outputs, returns three values (plan 2.4). + + +class wrong_count: + def process(self, x: float) -> tuple[float, float]: + return x, x, x diff --git a/core/tests/test_channels.cpp b/core/tests/test_channels.cpp new file mode 100644 index 0000000..628d7ac --- /dev/null +++ b/core/tests/test_channels.cpp @@ -0,0 +1,178 @@ +/// @file test_channels.cpp +/// @brief process() with several signal inputs and outputs (plan 2.4). +// SPDX-License-Identifier: MIT +// Copyright 2022-2026 Timothy Place. + +#include +#include +#include +#include +#include + +#include + +#include "support.h" + +using namespace tap::python; +using namespace tap::python::test; + +namespace { + + using channel_data = std::vector>; + + /// Run the host's `inputs` (one vector per channel, all the same length) through `p` into + /// `output_count` output channels, each starting as a sentinel so untouched samples show. + channel_data render_channels(processor& p, const channel_data& inputs, const std::size_t output_count, + const std::size_t frame_count) { + channel_data outputs(output_count, std::vector(frame_count, 12345.0)); + std::vector in; + std::vector out; + for (const auto& channel : inputs) { + in.push_back(channel.data()); + } + for (auto& channel : outputs) { + out.push_back(channel.data()); + } + p.process(in.data(), in.size(), out.data(), out.size(), frame_count); + return outputs; + } + + bool numpy_importable() { + gil_lock lock; + PyObject* numpy = PyImport_ImportModule("numpy"); + if (!numpy) { + PyErr_Clear(); + } + Py_XDECREF(numpy); + if (std::getenv("TAP_PYTHON_TEST_REQUIRE_EXAMPLES")) { + REQUIRE(numpy != nullptr); + } + return numpy != nullptr; + } + +} // namespace + +SCENARIO("process()'s parameters are its inputs and its return hint its outputs") { + ensure_runtime(); + const auto [name, block] = GENERATE(std::pair{"two_by_two", false}, std::pair{"block_two_by_two", true}); + if (block && !numpy_importable()) { + SKIP("numpy is not importable by the embedded interpreter"); + } + processor p{name}; + REQUIRE(p.load()); + p.prepare(48000.0, 4); + CHECK(p.input_count() == 2); + CHECK(p.output_count() == 2); + CHECK(p.block_mode() == block); + + THEN("each input arrives, and each output leaves, on its own channel") { + const auto out = render_channels(p, {{1.0, 2.0, 3.0, 4.0}, {0.5, 0.5, 1.0, 1.0}}, 2, 4); + CHECK(out[0] == std::vector{1.5, 2.5, 4.0, 5.0}); + CHECK(out[1] == std::vector{0.5, 1.5, 2.0, 3.0}); + } + WHEN("the host gives one input, and three outputs") { + const auto out = render_channels(p, {{1.0, 2.0, 3.0, 4.0}}, 3, 4); + THEN("the missing input is silence, and the extra output is silent") { + CHECK(out[0] == std::vector{1.0, 2.0, 3.0, 4.0}); + CHECK(out[1] == std::vector{1.0, 2.0, 3.0, 4.0}); + CHECK(all_equal(out[2], 0.0)); + } + } + WHEN("the host gives three inputs, and one output") { + const auto out = render_channels(p, {{1.0, 1.0, 1.0, 1.0}, {2.0, 2.0, 2.0, 2.0}, {9.0, 9.0, 9.0, 9.0}}, 1, 4); + THEN("the extra input is ignored, and the second output is dropped") { + CHECK(all_equal(out[0], 3.0)); + } + } + WHEN("the channels are the same memory (in place)") { + std::vector a{1.0, 2.0, 3.0, 4.0}; + std::vector b{0.5, 0.5, 1.0, 1.0}; + const double* in[2] = {a.data(), b.data()}; + double* out[2] = {a.data(), b.data()}; + p.process(in, 2, out, 2, 4); + THEN("every input sample is read before it is overwritten") { + CHECK(a == std::vector{1.5, 2.5, 4.0, 5.0}); + CHECK(b == std::vector{0.5, 1.5, 2.0, 3.0}); + } + } +} + +SCENARIO("process() with two inputs and one output gets both inputs") { + ensure_runtime(); + processor p{"two_inputs"}; + REQUIRE(p.load()); + CHECK(p.input_count() == 2); + CHECK(p.output_count() == 1); + const auto out = render_channels(p, {{3.0, 3.0}, {1.0, 2.0}}, 1, 2); + CHECK(out[0] == std::vector{2.0, 1.0}); +} + +SCENARIO("process() with no inputs is a generator") { + ensure_runtime(); + processor p{"generator"}; + REQUIRE(p.load()); + CHECK(p.input_count() == 0); + CHECK(p.output_count() == 1); + // the object still has a left inlet (for messages); a signal there is ignored + const auto out = render_channels(p, {{7.0, 7.0, 7.0}}, 1, 3); + CHECK(out[0] == std::vector{1.0, 2.0, 3.0}); +} + +SCENARIO("A process() whose inputs or outputs cannot be told is not bound, and says why") { + ensure_runtime(); + const auto [name, why] = + GENERATE(std::pair{"mixed_inputs", "mixes np.ndarray inputs (per vector) with others (per sample)"}, + std::pair{"star_inputs", "takes *args, but its parameters are the object's signal inputs"}, + std::pair{"tuple_return", "returns a tuple without saying how many values"}); + log_capture log; + processor p{name, log.sink()}; + forget_loaded(name); // this load runs the file, so says what is wrong with the class + REQUIRE(p.load()); + CHECK_FALSE(p.has_process()); + CHECK(log.contains(why, log_level::error)); + CHECK(log.contains("audio is not bound", log_level::error)); + CHECK(all_equal(render_channels(p, {{1.0, 1.0}}, 1, 2)[0], 0.0)); +} + +SCENARIO("A process() returning the wrong number of values is silent, and reported once") { + ensure_runtime(); + log_capture log; + processor p{"wrong_count", log.sink()}; + REQUIRE(p.load()); + CHECK(p.output_count() == 2); + const auto out = render_channels(p, {{1.0, 1.0}}, 2, 2); + CHECK(all_equal(out[0], 0.0)); + CHECK(all_equal(out[1], 0.0)); + render_channels(p, {{1.0, 1.0}}, 2, 2); + p.flush_reports(); + const auto lines = log.lines(); + CHECK(std::count_if(lines.begin(), lines.end(), + [](const log_capture::line& l) { + return l.text.find("returned 3 value(s) for 2 outputs") != std::string::npos; + }) + == 1); +} + +SCENARIO("The inputs and outputs follow the class across reloads, and survive a failed one") { + ensure_runtime(); + write_script("reshaped", "class reshaped:\n" + " def process(self, x: float) -> float:\n" + " return x\n"); + processor p{"reshaped"}; + REQUIRE(p.load()); + CHECK(p.input_count() == 1); + CHECK(p.output_count() == 1); + + write_script("reshaped", "class reshaped:\n" + " def process(self, a: float, b: float, c: float) -> tuple[float, float]:\n" + " return a, b + c\n"); + REQUIRE(p.load()); + CHECK(p.input_count() == 3); + CHECK(p.output_count() == 2); + CHECK(render_channels(p, {{1.0}, {2.0}, {3.0}}, 2, 1) == channel_data{{1.0}, {5.0}}); + + write_script("reshaped", "class reshaped:\n def (\n"); + CHECK_FALSE(p.load()); + CHECK(p.input_count() == 3); + CHECK(p.output_count() == 2); +} diff --git a/core/tests/test_processor.cpp b/core/tests/test_processor.cpp index fc247e5..5c46802 100644 --- a/core/tests/test_processor.cpp +++ b/core/tests/test_processor.cpp @@ -294,31 +294,17 @@ SCENARIO("process() raising silences the rest of the vector and unbinds until th } } -SCENARIO("process() declaring a tuple return is not bound") { +SCENARIO("process() returning a tuple of unsaid length is not bound") { ensure_runtime(); log_capture log; processor p{"tuple_return", log.sink()}; REQUIRE(p.load()); CHECK_FALSE(p.has_process()); - CHECK(log.contains("process() returns a tuple", log_level::error)); + CHECK(log.contains("process() returns a tuple without saying how many values", log_level::error)); CHECK(all_equal(render(p, 1.0), 0.0)); } -SCENARIO("process() declaring more than one input is bound with a warning, and then fails") { - ensure_runtime(); - log_capture log; - processor p{"two_inputs", log.sink()}; - - REQUIRE(p.load()); - CHECK(log.contains("process() declares 2 inputs but only the first is supported", log_level::error)); - CHECK(p.has_process()); - - // honest limit (Phase 2.4): the call passes one argument, so the first sample raises TypeError - CHECK(all_equal(render(p, 1.0), 0.0)); - CHECK_FALSE(p.has_process()); -} - // The reload scenarios are linear (no sibling sections): Catch2 re-runs a scenario once per // section, and each re-run would start from the file the previous one left behind. diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index 76ab71f..4239725 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -101,7 +101,19 @@ while audio ran segfaulted in 5 of 5 runs. newly loaded instance before it is published, so no vector ever runs on an unprepared instance. `allpass.py` uses it (and its α range is now open, per 5.4). - [ ] **2.4 Multiple inlets/outlets** — `process` arguments define signal inlets and a tuple - return defines outlets, fixed at construction. + return defines outlets, fixed at construction. *Decided (2026-09-30):* when a save changes the + counts, the object adapts its inlets and outlets in place with Max's dynamic inlets and outlets + (`dynlet_begin`/`dynlet_end` around `dsp_resize` and `outlet_append`/`outlet_delete`, as + Cycling '74 describes in its developer forum) rather than asking for the object to be + re-created. Three steps: *(a) the core — done:* `processor::process()` takes N input and M + output channels; the positional parameters are the inputs (all `np.ndarray` or all per sample; + none makes a generator), the return hint the outputs (`tuple[float, float]` for two; a tuple of + unsaid length, `*args` or mixed hints are reported and not bound); `input_count()` and + `output_count()` tell the host; the host's channels are matched to the class's (a missing input + reads as silence, an extra output is silent); a result of the wrong length is silenced and + reported once per load. *(b) the Max object's inlets and outlets from the class at creation; + (c) adapting them on reload (dynlets).* Until (b), the object keeps one inlet and one outlet: a + class with two inputs binds, its second input silent. - [ ] **2.5 Worker mode (D1)** — `@mode worker`: Python on a worker thread, lock-free FIFO, latency reported to Max, underrun → silence. - [x] **2.6 Shorter reload stalls** — compile outside the swap and hold the GIL only for the swap. diff --git a/source/projects/tap.python_tilde/tap.python_tilde.h b/source/projects/tap.python_tilde/tap.python_tilde.h index 123a07b..a056702 100644 --- a/source/projects/tap.python_tilde/tap.python_tilde.h +++ b/source/projects/tap.python_tilde/tap.python_tilde.h @@ -267,15 +267,18 @@ class python : public object, public vector_operator<> { } } - /// The audio perform routine: the core calls the Python process() once per - /// sample, holding the GIL for the vector, and outputs silence while unbound. + /// The audio perform routine: the core calls the Python process() once per sample or per + /// vector, holding the GIL for the vector, and outputs silence while unbound. void operator()(audio_bundle input, audio_bundle output) { if (!m_processor) { output.clear(); return; } try { - m_processor->process(input.samples(0), output.samples(0), static_cast(input.frame_count())); + // every channel Max gives: the core matches them to what process() declares (plan 2.4) + m_processor->process(input.samples(), static_cast(input.channel_count()), output.samples(), + static_cast(output.channel_count()), + static_cast(input.frame_count())); } catch (...) { // never let an exception unwind into the audio driver output.clear(); From 27878542acdf742c0bcb2a8b0216090def671c88 Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Wed, 30 Sep 2026 10:28:11 -0500 Subject: [PATCH 05/15] 2.4 (b): the object's inlets and outlets from the class, when it is made MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- CHANGELOG.md | 13 + CLAUDE.md | 3 +- ReadMe.md | 2 +- core/include/tap/python/processor.h | 26 +- core/tests/test_examples.cpp | 40 + docs/PRODUCTION-PLAN.md | 12 +- python/stereo_width.py | 25 + runtime-tests/make_patchers.py | 42 +- .../tap.python~.channels.maxtest.maxpat | 2566 +++++++++++++++++ runtime-tests/python/maxtest_editor.py | 10 + runtime-tests/python/maxtest_generator.py | 9 + runtime-tests/python/maxtest_shape.py | 8 + .../tap.python_tilde/tap.python_tilde.h | 59 +- .../tap.python_tilde_test.cpp | 43 +- 14 files changed, 2838 insertions(+), 20 deletions(-) create mode 100644 python/stereo_width.py create mode 100644 runtime-tests/patchers/tap.python~.channels.maxtest.maxpat create mode 100644 runtime-tests/python/maxtest_generator.py create mode 100644 runtime-tests/python/maxtest_shape.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e369e6..82e7f8f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,19 @@ breaking changes to the contract are allowed where they buy correctness (D5 in ## Unreleased +### Added — several inputs and outputs + +- **process() can take several signal inputs and return several outputs.** Its parameters are the + object's signal inlets and its return hint its outlets: `process(self, left: np.ndarray, right: + np.ndarray) -> tuple[np.ndarray, np.ndarray]` makes `[tap.python~ …]` with two of each, and + `process(self) -> float` a generator (with one inlet still, for messages). The inputs are all + `np.ndarray` or all per sample; a tuple return must say how many values it has. A return with the + wrong number of values is output as silence and reported once. New example: `stereo_width.py`. + The object takes its inlets and outlets from the class when it is made; a save that changes how + many is reported, and takes effect when the object is re-created. (Plan 2.4.) *Changed with it:* + `process()` taking `*args` is now reported and not bound (before, it was bound and its extra + arguments never arrived). + ### Changed — a broken file is reported once - **A save that breaks a class file is reported once, however many objects share it.** Every diff --git a/CLAUDE.md b/CLAUDE.md index c85a86d..f686ca0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,7 +37,8 @@ its phases, and the audit findings behind them. Tick its items (with the PR) as `_test.cpp` drives the Max glue through min-api's mock kernel. - **`python/`** — the user's script folder in the package (and the examples: `default.py`, `numpy_gain.py`, `allpass.py`, `numpy_allpass.py` — the same filter per vector, checked equal - sample for sample by the core battery — and `allpass-doc.ipynb`). + sample for sample by the core battery — `stereo_width.py`, two inputs and two outputs, and + `allpass-doc.ipynb`). - **`runtime-tests/`** — tests that run inside a real Max (plan 6.1): Cycling '74's max-test harness (submodule), patchers generated by `make_patchers.py` (edit the generator, never the patchers), fixtures (`python/maxtest_*.py`, copied into `python/` for a run) and `run.py`, which installs the diff --git a/ReadMe.md b/ReadMe.md index f66377e..7f06f0b 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -92,7 +92,7 @@ Python sources live in the package's `python` folder. `[tap.python~ name]` loads - `process(self, x: np.ndarray) -> np.ndarray` is called **once per signal vector** with a numpy array of the input and must return an array of the same length (any numeric dtype, or a list; it is converted). This is the form to use for anything that must run in real time — see `python/numpy_gain.py`, and `python/numpy_allpass.py` for a filter with feedback. The input array is reused from one call to the next: copy it if you want to keep it. - `process(self, x: float) -> float` is called **once per sample** — simplest for sketching; the call is cheap, but every line of Python in it runs once per sample (see [the performance note](#a-note-on-performance)). - One signal inlet and one signal outlet, single-channel; wrap the object in `mc.` for multichannel. (Returning a tuple for multiple outputs is not supported yet.) Output that is not a number, or not finite (NaN, infinity), is replaced with 0.0 and reported once in the Max console. + Its parameters are the object's signal inlets and its return hint its outlets: `process(self, left: np.ndarray, right: np.ndarray) -> tuple[np.ndarray, np.ndarray]` makes an object with two of each (see `python/stereo_width.py`), and `process(self) -> float`, with no inputs, a generator — the first inlet is always there, for messages. The inputs are all `np.ndarray` or all per sample, and a tuple return must say how many values it has (`tuple[float, float]`). The object takes its inlets and outlets from the class when it is made; if a save changes how many, the console says so, and until the object is re-created an input it lacks reads as silence and an output it lacks is dropped. Wrap the object in `mc.` to run one instance per channel of a multichannel signal. Output that is not a number, or not finite (NaN, infinity), is replaced with 0.0 and reported once in the Max console, as is a return with the wrong number of values. - **Audio settings** — an optional method `prepare(self, sample_rate: float, vector_size: int) -> None` is called with Max's sample rate and vector size before the object processes any audio, again whenever they change, and on every reload before the new code runs. `python/allpass.py` uses it to size its delay line. - **Hot reload** — saving the `.py` file reloads it in place, as a fresh module (names you deleted from the file are gone): the attributes and messages follow the new class, and audio resumes with the new code. Until the new code is ready the object keeps running the old one, so a successful reload swaps in without a gap in the audio. Attribute values carry over — set from the patcher or by your own code — for every attribute the new class still has with the same type; an attribute whose type changed starts from its new default, and one you removed disappears from the object. If the file has an error, the object prints the traceback to the Max console and outputs silence until the next successful reload (and the attribute values come back with it); a save that breaks a file shared by many objects is reported once, not by each, while an object created later with the file still broken says so again. Every object using the same file shares one execution of it per save, and the console says so once — `Loaded name.py: process() bound, one call per sample` (or per vector), from whichever object ran the file — along with anything true of the class, such as a method skipped for its name; a save that changes nothing reloads silently. Errors that belong to one object, such as an exception in its constructor, are still reported by each. Max's file watcher notices a save within a couple of seconds, but it coalesces saves made in quick succession — a script saving once a second, say — so the object then reloads for only some of them, and can lag behind until they stop; sending the object `filechanged` reloads it at once. - **Errors** — an exception raised by your code (in `process()`, a message, an attribute setter, the constructor or at import) prints its traceback to the Max console; it never takes Max down. That includes `sys.exit()`, which is reported like any other exception rather than quitting Max. diff --git a/core/include/tap/python/processor.h b/core/include/tap/python/processor.h index 91f885a..917846e 100644 --- a/core/include/tap/python/processor.h +++ b/core/include/tap/python/processor.h @@ -123,6 +123,10 @@ namespace tap::python { std::size_t input_count() const noexcept { return m_inputs; } std::size_t output_count() const noexcept { return m_outputs; } + /// The names of process()'s input parameters, in order (for the host's inlet help). Main + /// thread, after load(). + const std::vector& input_names() const noexcept { return m_input_names; } + /// The most inputs, and the most outputs, a process() may declare. static constexpr std::size_t k_max_channels = 64; @@ -226,6 +230,7 @@ namespace tap::python { previous.block_mode = std::exchange(m_block_mode, next.block_mode); m_inputs = next.inputs; m_outputs = next.outputs; + previous.input_names = std::exchange(m_input_names, std::move(next.input_names)); previous.attributes = std::exchange(m_attributes, std::move(next.attributes)); previous.messages = std::exchange(m_messages, std::move(next.messages)); next.instance = nullptr; @@ -505,6 +510,7 @@ namespace tap::python { bool block_mode{}; // process() takes and returns np.ndarray std::size_t inputs{1}; // the signal inputs process() declares std::size_t outputs{1}; // and the outputs + std::vector input_names; // process()'s input parameters std::vector attributes; std::vector messages; }; @@ -522,11 +528,12 @@ namespace tap::python { std::vector m_attributes; std::vector m_messages; // The rest of the binding and the block buffer: read and written only under the GIL. - PyObject* m_prepare_function{}; // strong, or null - bool m_block_mode{}; - std::size_t m_inputs{1}; // the bound process()'s inputs and outputs - std::size_t m_outputs{1}; - bool m_announcing{}; // this load() ran the file: see announce() + PyObject* m_prepare_function{}; // strong, or null + bool m_block_mode{}; + std::size_t m_inputs{1}; // the bound process()'s inputs and outputs + std::size_t m_outputs{1}; + std::vector m_input_names; // main thread only + bool m_announcing{}; // this load() ran the file: see announce() // The np.ndarray each input arrives in, reused every vector: strong, its buffer held so its // memory cannot move. struct block_buffer { @@ -1272,12 +1279,14 @@ namespace tap::python { } // 2.4: the positional parameters are the signal inputs, all per vector (np.ndarray) or all // per sample; the return hint names the outputs — one value, or tuple[...] of n - std::size_t inputs = 0; - std::size_t per_vector = 0; - bool var_inputs = false; + std::size_t inputs = 0; + std::size_t per_vector = 0; + bool var_inputs = false; + std::vector names; for (const auto& p : sig->parameters) { if (p.parameter_kind == k_positional_only || p.parameter_kind == k_positional_or_named) { ++inputs; + names.push_back(p.name); per_vector += p.kind == "ndarray" ? 1 : 0; } var_inputs = var_inputs || p.parameter_kind == k_var_positional; @@ -1309,6 +1318,7 @@ namespace tap::python { b.block_mode = block_input; // announced by load() once the binding is in place b.inputs = inputs; b.outputs = outputs; + b.input_names = std::move(names); } /// Bind a public method as a message, described by its signature. A keyword-only parameter diff --git a/core/tests/test_examples.cpp b/core/tests/test_examples.cpp index 1140fd8..1719678 100644 --- a/core/tests/test_examples.cpp +++ b/core/tests/test_examples.cpp @@ -169,3 +169,43 @@ SCENARIO("numpy_allpass.py computes exactly what allpass.py does, a vector at a } CHECK(identical); } + +SCENARIO("stereo_width.py has two inputs and two outputs, and sets the width") { + ensure_runtime(); + if (!importable("attrs") || !importable("numpy")) { + SKIP("attrs and numpy are not importable by the embedded interpreter"); + } + + processor p{"stereo_width"}; + REQUIRE(p.load()); + p.prepare(48000.0, 4); + CHECK(p.input_count() == 2); + CHECK(p.output_count() == 2); + CHECK(p.input_names() == std::vector{"left", "right"}); + + std::vector left{1.0, 0.5, 0.0, -0.5}; + std::vector right{0.0, 0.5, 1.0, 0.5}; + std::vector out_left(4); + std::vector out_right(4); + const double* in[2] = {left.data(), right.data()}; + double* out[2] = {out_left.data(), out_right.data()}; + + WHEN("the width is 1") { + p.process(in, 2, out, 2, 4); + THEN("the pair passes as it was") { + CHECK(out_left == left); + CHECK(out_right == right); + } + } + WHEN("the width is 0") { + REQUIRE(p.set_attribute("width", 0.0)); + p.process(in, 2, out, 2, 4); + THEN("both channels are the mono mix") { + CHECK(out_left == std::vector{0.5, 0.5, 0.5, 0.0}); + CHECK(out_right == out_left); + } + } + THEN("a negative width is refused") { + CHECK_FALSE(p.set_attribute("width", -1.0)); + } +} diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index 4239725..6d9547c 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -111,9 +111,15 @@ while audio ran segfaulted in 5 of 5 runs. unsaid length, `*args` or mixed hints are reported and not bound); `input_count()` and `output_count()` tell the host; the host's channels are matched to the class's (a missing input reads as silence, an extra output is silent); a result of the wrong length is silenced and - reported once per load. *(b) the Max object's inlets and outlets from the class at creation; - (c) adapting them on reload (dynlets).* Until (b), the object keeps one inlet and one outlet: a - class with two inputs binds, its second input silent. + reported once per load. *(b) the Max object's inlets and outlets from the class at creation — + done:* the constructor adds an `inlet<>` per input after the first (its help naming the + parameter: `processor::input_names()`) and an `outlet<>` per 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. New example `stereo_width.py` (two in, two out; `width`). Mock test: + `[tap.python~ stereo_width]` has two of each and processes both (the test file now stands in a + faithful `attr_args_offset`, and the object reads a one-symbol argument directly, not through + `atom_gettext` — the mock's gives nothing); runtime test `channels` (stereo_width, a generator, a + save that changes the shape). *(c) adapting them on reload (dynlets).* - [ ] **2.5 Worker mode (D1)** — `@mode worker`: Python on a worker thread, lock-free FIFO, latency reported to Max, underrun → silence. - [x] **2.6 Shorter reload stalls** — compile outside the swap and hold the GIL only for the swap. diff --git a/python/stereo_width.py b/python/stereo_width.py new file mode 100644 index 0000000..3b8883b --- /dev/null +++ b/python/stereo_width.py @@ -0,0 +1,25 @@ +import numpy as np +from attrs import define, field + + +@define +class stereo_width: + """Stereo width: two signal inputs and two outputs, left and right. + + process()'s parameters are the object's signal inlets — [tap.python~ stereo_width] has two — + and its return hint, tuple[np.ndarray, np.ndarray], gives it two outlets. The signal is split + into what the channels share (mid) and what differs (side); width scales the side: 0 folds + the pair to mono, 1 leaves it as it was, more than 1 widens it. + """ + + width: float = field(default = 1.0) + + @width.validator + def _check_width(self, attribute, value): + if value < 0.0: + raise ValueError("width must be 0 or more") + + def process(self, left: np.ndarray, right: np.ndarray) -> tuple[np.ndarray, np.ndarray]: + mid = (left + right) * 0.5 + side = (left - right) * (0.5 * self.width) + return mid + side, mid - side diff --git a/runtime-tests/make_patchers.py b/runtime-tests/make_patchers.py index 2c25b76..27803b7 100644 --- a/runtime-tests/make_patchers.py +++ b/runtime-tests/make_patchers.py @@ -557,6 +557,45 @@ def many_instances() -> Test: return t +def channels() -> Test: + t = Test("tap.python~.channels.maxtest.maxpat", + "Several inputs and outputs (plan 2.4): process()'s parameters are the object's signal inlets " + "and its return hint its outlets — stereo_width's two of each, a generator's none (one inlet " + "still, for messages). A save that changes how many keeps the object's inlets and outlets " + "until it is re-created: a missing output is silent.") + left, right = t.signal(0.8), t.signal(0.2) + width = t.obj("tap.python~ stereo_width", inlets=2, outlets=2, signal=True) + t.patcher.connect(left, 0, width, 0) + t.patcher.connect(right, 0, width, 1) + generator = t.python("maxtest_generator") + a, b = t.signal(0.3), t.signal(0.6) + shape = t.obj("tap.python~ maxtest_shape", inlets=2, outlets=2, signal=True) + t.patcher.connect(a, 0, shape, 0) + t.patcher.connect(b, 0, shape, 1) + editor = t.python("maxtest_editor", column=1) + + def outlet(box: str, n: int) -> str: # a box passing outlet n of `box` on, to sample + through = t.patcher.box("+~ 0.", inlets=2, column=3, outlettype=["signal"]) + t.patcher.connect(box, n, through) + return through + + width_left, width_right = outlet(width, 0), outlet(width, 1) + shape_first, shape_second = outlet(shape, 0), outlet(shape, 1) + t.step(t.sample_equals("stereo-left-at-width-1", width_left, 0.8), + t.sample_equals("stereo-right-at-width-1", width_right, 0.2), + t.sample_equals("generator-without-inputs", generator, 0.25), + t.sample_equals("second-input-to-second-output", shape_second, 0.6)) + t.step(t.send("width 0", width), t.send("level 0.5", generator)) + t.step(t.sample_equals("mono-left-at-width-0", width_left, 0.5), + t.sample_equals("mono-right-at-width-0", width_right, 0.5), + t.sample_equals("generator-takes-messages", generator, 0.5)) + t.step(t.send("reshape maxtest_shape 1 1", editor), t.send("filechanged", shape)) + t.step(t.sample_equals("reshaped-first-output", shape_first, 0.3), + t.sample_equals("output-the-class-lost-is-silent", shape_second, 0.0), + t.errors_are("console-clean", "== 0"), wait=WATCH) + return t + + def announce_once() -> Test: t = Test("tap.python~.announce-once.maxtest.maxpat", "What is true of a class is said once per run of its file, however many objects share it " @@ -768,7 +807,8 @@ def without_runtime_restart() -> Test: return t -TESTS_TO_WRITE = [load, attributes_and_messages, reload, reload_under_audio, many_instances, announce_once, faults, +TESTS_TO_WRITE = [load, attributes_and_messages, reload, reload_under_audio, many_instances, channels, announce_once, + faults, prepare, without_runtime, without_runtime_restart] diff --git a/runtime-tests/patchers/tap.python~.channels.maxtest.maxpat b/runtime-tests/patchers/tap.python~.channels.maxtest.maxpat new file mode 100644 index 0000000..60dd084 --- /dev/null +++ b/runtime-tests/patchers/tap.python~.channels.maxtest.maxpat @@ -0,0 +1,2566 @@ +{ + "patcher": { + "fileversion": 1, + "appversion": { + "major": 9, + "minor": 0, + "revision": 8, + "architecture": "x64", + "modernui": 1 + }, + "classnamespace": "box", + "rect": [ + 60.0, + 80.0, + 1290, + 900.0 + ], + "default_fontsize": 12.0, + "default_fontname": "Arial", + "gridsize": [ + 15.0, + 15.0 + ], + "description": "tap.python~.channels", + "boxes": [ + { + "box": { + "id": "obj-1", + "maxclass": "comment", + "numinlets": 1, + "numoutlets": 0, + "patching_rect": [ + 20.0, + 20.0, + 480, + 80.0 + ], + "text": "tap.python~.channels\n\nSeveral inputs and outputs (plan 2.4): process()'s parameters are the object's signal inlets and its return hint its outlets \u2014 stereo_width's two of each, a generator's none (one inlet still, for messages). A save that changes how many keeps the object's inlets and outlets until it is re-created: a missing output is silent.", + "linecount": 4 + } + }, + { + "box": { + "id": "obj-2", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 520.0, + 20.0, + 72.0, + 22.0 + ], + "text": "sig~ 0.8" + } + }, + { + "box": { + "id": "obj-3", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 520.0, + 50.0, + 72.0, + 22.0 + ], + "text": "sig~ 0.2" + } + }, + { + "box": { + "id": "obj-4", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 2, + "outlettype": [ + "signal", + "signal" + ], + "patching_rect": [ + 520.0, + 80.0, + 184.0, + 22.0 + ], + "text": "tap.python~ stereo_width" + } + }, + { + "box": { + "id": "obj-5", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 520.0, + 110.0, + 219.0, + 22.0 + ], + "text": "tap.python~ maxtest_generator" + } + }, + { + "box": { + "id": "obj-6", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 520.0, + 140.0, + 72.0, + 22.0 + ], + "text": "sig~ 0.3" + } + }, + { + "box": { + "id": "obj-7", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 520.0, + 170.0, + 72.0, + 22.0 + ], + "text": "sig~ 0.6" + } + }, + { + "box": { + "id": "obj-8", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 2, + "outlettype": [ + "signal", + "signal" + ], + "patching_rect": [ + 520.0, + 200.0, + 191.0, + 22.0 + ], + "text": "tap.python~ maxtest_shape" + } + }, + { + "box": { + "id": "obj-9", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 270.0, + 20.0, + 198.0, + 22.0 + ], + "text": "tap.python~ maxtest_editor" + } + }, + { + "box": { + "id": "obj-10", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 770.0, + 20.0, + 51.0, + 22.0 + ], + "text": "+~ 0." + } + }, + { + "box": { + "id": "obj-11", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 770.0, + 50.0, + 51.0, + 22.0 + ], + "text": "+~ 0." + } + }, + { + "box": { + "id": "obj-12", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 770.0, + 80.0, + 51.0, + 22.0 + ], + "text": "+~ 0." + } + }, + { + "box": { + "id": "obj-13", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 770.0, + 110.0, + 51.0, + 22.0 + ], + "text": "+~ 0." + } + }, + { + "box": { + "id": "obj-14", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 140.0, + 177.0, + 22.0 + ], + "text": "test.sample~ @autorun 0" + } + }, + { + "box": { + "id": "obj-15", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 170.0, + 121.0, + 22.0 + ], + "text": "test.equals 0.8" + } + }, + { + "box": { + "id": "obj-16", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 200.0, + 254.0, + 22.0 + ], + "text": "test.assert stereo-left-at-width-1" + } + }, + { + "box": { + "id": "obj-17", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 230.0, + 177.0, + 22.0 + ], + "text": "test.sample~ @autorun 0" + } + }, + { + "box": { + "id": "obj-18", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 260.0, + 121.0, + 22.0 + ], + "text": "test.equals 0.2" + } + }, + { + "box": { + "id": "obj-19", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 290.0, + 261.0, + 22.0 + ], + "text": "test.assert stereo-right-at-width-1" + } + }, + { + "box": { + "id": "obj-20", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 320.0, + 177.0, + 22.0 + ], + "text": "test.sample~ @autorun 0" + } + }, + { + "box": { + "id": "obj-21", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 350.0, + 128.0, + 22.0 + ], + "text": "test.equals 0.25" + } + }, + { + "box": { + "id": "obj-22", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 380.0, + 268.0, + 22.0 + ], + "text": "test.assert generator-without-inputs" + } + }, + { + "box": { + "id": "obj-23", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 410.0, + 177.0, + 22.0 + ], + "text": "test.sample~ @autorun 0" + } + }, + { + "box": { + "id": "obj-24", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 440.0, + 121.0, + 22.0 + ], + "text": "test.equals 0.6" + } + }, + { + "box": { + "id": "obj-25", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 470.0, + 303.0, + 22.0 + ], + "text": "test.assert second-input-to-second-output" + } + }, + { + "box": { + "id": "obj-26", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 270.0, + 50.0, + 65.0, + 22.0 + ], + "text": "width 0" + } + }, + { + "box": { + "id": "obj-27", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 270.0, + 80.0, + 79.0, + 22.0 + ], + "text": "level 0.5" + } + }, + { + "box": { + "id": "obj-28", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 500.0, + 177.0, + 22.0 + ], + "text": "test.sample~ @autorun 0" + } + }, + { + "box": { + "id": "obj-29", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 530.0, + 121.0, + 22.0 + ], + "text": "test.equals 0.5" + } + }, + { + "box": { + "id": "obj-30", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 560.0, + 240.0, + 22.0 + ], + "text": "test.assert mono-left-at-width-0" + } + }, + { + "box": { + "id": "obj-31", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 590.0, + 177.0, + 22.0 + ], + "text": "test.sample~ @autorun 0" + } + }, + { + "box": { + "id": "obj-32", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 620.0, + 121.0, + 22.0 + ], + "text": "test.equals 0.5" + } + }, + { + "box": { + "id": "obj-33", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 650.0, + 247.0, + 22.0 + ], + "text": "test.assert mono-right-at-width-0" + } + }, + { + "box": { + "id": "obj-34", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 680.0, + 177.0, + 22.0 + ], + "text": "test.sample~ @autorun 0" + } + }, + { + "box": { + "id": "obj-35", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 710.0, + 121.0, + 22.0 + ], + "text": "test.equals 0.5" + } + }, + { + "box": { + "id": "obj-36", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 740.0, + 268.0, + 22.0 + ], + "text": "test.assert generator-takes-messages" + } + }, + { + "box": { + "id": "obj-37", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 270.0, + 110.0, + 191.0, + 22.0 + ], + "text": "reshape maxtest_shape 1 1" + } + }, + { + "box": { + "id": "obj-38", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 270.0, + 140.0, + 93.0, + 22.0 + ], + "text": "filechanged" + } + }, + { + "box": { + "id": "obj-39", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 770.0, + 177.0, + 22.0 + ], + "text": "test.sample~ @autorun 0" + } + }, + { + "box": { + "id": "obj-40", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 800.0, + 121.0, + 22.0 + ], + "text": "test.equals 0.3" + } + }, + { + "box": { + "id": "obj-41", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 830.0, + 247.0, + 22.0 + ], + "text": "test.assert reshaped-first-output" + } + }, + { + "box": { + "id": "obj-42", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 860.0, + 177.0, + 22.0 + ], + "text": "test.sample~ @autorun 0" + } + }, + { + "box": { + "id": "obj-43", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 890.0, + 121.0, + 22.0 + ], + "text": "test.equals 0.0" + } + }, + { + "box": { + "id": "obj-44", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 920.0, + 317.0, + 22.0 + ], + "text": "test.assert output-the-class-lost-is-silent" + } + }, + { + "box": { + "id": "obj-45", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 20.0, + 65.0, + 22.0 + ], + "text": "error 1" + } + }, + { + "box": { + "id": "obj-46", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 50.0, + 40.0, + 22.0 + ], + "text": "t b" + } + }, + { + "box": { + "id": "obj-47", + "maxclass": "newobj", + "numinlets": 3, + "numoutlets": 4, + "outlettype": [ + "", + "", + "", + "" + ], + "patching_rect": [ + 1020.0, + 80.0, + 135.0, + 22.0 + ], + "text": "counter 1 1000000" + } + }, + { + "box": { + "id": "obj-48", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 110.0, + 40.0, + 22.0 + ], + "text": "i" + } + }, + { + "box": { + "id": "obj-49", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 140.0, + 44.0, + 22.0 + ], + "text": "== 0" + } + }, + { + "box": { + "id": "obj-50", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 950.0, + 191.0, + 22.0 + ], + "text": "test.assert console-clean" + } + }, + { + "box": { + "id": "obj-51", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 0, + "outlettype": [], + "patching_rect": [ + 20.0, + 108.0, + 114.0, + 22.0 + ], + "text": "test.terminate" + } + }, + { + "box": { + "id": "obj-52", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 170.0, + 72.0, + 22.0 + ], + "text": "tosymbol" + } + }, + { + "box": { + "id": "obj-53", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 5, + "outlettype": [ + "", + "", + "", + "", + "" + ], + "patching_rect": [ + 1020.0, + 200.0, + 177.0, + 22.0 + ], + "text": "regexp \\\" @substitute '" + } + }, + { + "box": { + "id": "obj-54", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 230.0, + 86.0, + 22.0 + ], + "text": "fromsymbol" + } + }, + { + "box": { + "id": "obj-55", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 1020.0, + 260.0, + 51.0, + 22.0 + ], + "text": "t l b" + } + }, + { + "box": { + "id": "obj-56", + "maxclass": "newobj", + "numinlets": 3, + "numoutlets": 4, + "outlettype": [ + "", + "", + "", + "" + ], + "patching_rect": [ + 1020.0, + 290.0, + 135.0, + 22.0 + ], + "text": "counter 1 1000000" + } + }, + { + "box": { + "id": "obj-57", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 320.0, + 51.0, + 22.0 + ], + "text": "<= 50" + } + }, + { + "box": { + "id": "obj-58", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 350.0, + 72.0, + 22.0 + ], + "text": "gate 1 1" + } + }, + { + "box": { + "id": "obj-59", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 0, + "outlettype": [], + "patching_rect": [ + 1020.0, + 380.0, + 170.0, + 22.0 + ], + "text": "test.log console-error" + } + }, + { + "box": { + "id": "obj-60", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 138.0, + 72.0, + 22.0 + ], + "text": "loadbang" + } + }, + { + "box": { + "id": "obj-61", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 168.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-62", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 198.0, + 93.0, + 22.0 + ], + "text": "; dsp start" + } + }, + { + "box": { + "id": "obj-63", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 228.0, + 93.0, + 22.0 + ], + "text": "delay 60000" + } + }, + { + "box": { + "id": "obj-64", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 4, + "outlettype": [ + "", + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 258.0, + 79.0, + 22.0 + ], + "text": "dspstate~" + } + }, + { + "box": { + "id": "obj-65", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 288.0, + 51.0, + 22.0 + ], + "text": "sel 1" + } + }, + { + "box": { + "id": "obj-66", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 318.0, + 79.0, + 22.0 + ], + "text": "onebang 1" + } + }, + { + "box": { + "id": "obj-67", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 348.0, + 40.0, + 22.0 + ], + "text": "1" + } + }, + { + "box": { + "id": "obj-68", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 980.0, + 191.0, + 22.0 + ], + "text": "test.assert audio-started" + } + }, + { + "box": { + "id": "obj-69", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 378.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-70", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 5, + "outlettype": [ + "", + "", + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 408.0, + 93.0, + 22.0 + ], + "text": "t b b b b b" + } + }, + { + "box": { + "id": "obj-71", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 438.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-72", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 3, + "outlettype": [ + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 468.0, + 65.0, + 22.0 + ], + "text": "t b b b" + } + }, + { + "box": { + "id": "obj-73", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 498.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-74", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 4, + "outlettype": [ + "", + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 528.0, + 79.0, + 22.0 + ], + "text": "t b b b b" + } + }, + { + "box": { + "id": "obj-75", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 558.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-76", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 3, + "outlettype": [ + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 588.0, + 65.0, + 22.0 + ], + "text": "t b b b" + } + }, + { + "box": { + "id": "obj-77", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 618.0, + 86.0, + 22.0 + ], + "text": "delay 2500" + } + }, + { + "box": { + "id": "obj-78", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 4, + "outlettype": [ + "", + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 648.0, + 79.0, + 22.0 + ], + "text": "t b b b b" + } + }, + { + "box": { + "id": "obj-79", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 678.0, + 79.0, + 22.0 + ], + "text": "delay 500" + } + }, + { + "box": { + "id": "obj-80", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 708.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + } + ], + "lines": [ + { + "patchline": { + "source": [ + "obj-2", + 0 + ], + "destination": [ + "obj-4", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-3", + 0 + ], + "destination": [ + "obj-4", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-6", + 0 + ], + "destination": [ + "obj-8", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-7", + 0 + ], + "destination": [ + "obj-8", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-4", + 0 + ], + "destination": [ + "obj-10", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-4", + 1 + ], + "destination": [ + "obj-11", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-8", + 0 + ], + "destination": [ + "obj-12", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-8", + 1 + ], + "destination": [ + "obj-13", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-10", + 0 + ], + "destination": [ + "obj-14", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-14", + 0 + ], + "destination": [ + "obj-15", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-15", + 0 + ], + "destination": [ + "obj-16", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-11", + 0 + ], + "destination": [ + "obj-17", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-17", + 0 + ], + "destination": [ + "obj-18", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-18", + 0 + ], + "destination": [ + "obj-19", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-5", + 0 + ], + "destination": [ + "obj-20", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-20", + 0 + ], + "destination": [ + "obj-21", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-21", + 0 + ], + "destination": [ + "obj-22", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-13", + 0 + ], + "destination": [ + "obj-23", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-23", + 0 + ], + "destination": [ + "obj-24", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-24", + 0 + ], + "destination": [ + "obj-25", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-26", + 0 + ], + "destination": [ + "obj-4", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-27", + 0 + ], + "destination": [ + "obj-5", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-10", + 0 + ], + "destination": [ + "obj-28", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-28", + 0 + ], + "destination": [ + "obj-29", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-29", + 0 + ], + "destination": [ + "obj-30", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-11", + 0 + ], + "destination": [ + "obj-31", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-31", + 0 + ], + "destination": [ + "obj-32", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-32", + 0 + ], + "destination": [ + "obj-33", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-5", + 0 + ], + "destination": [ + "obj-34", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-34", + 0 + ], + "destination": [ + "obj-35", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-35", + 0 + ], + "destination": [ + "obj-36", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-37", + 0 + ], + "destination": [ + "obj-9", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-38", + 0 + ], + "destination": [ + "obj-8", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-12", + 0 + ], + "destination": [ + "obj-39", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-39", + 0 + ], + "destination": [ + "obj-40", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-40", + 0 + ], + "destination": [ + "obj-41", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-13", + 0 + ], + "destination": [ + "obj-42", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-42", + 0 + ], + "destination": [ + "obj-43", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-43", + 0 + ], + "destination": [ + "obj-44", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-45", + 0 + ], + "destination": [ + "obj-46", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-46", + 0 + ], + "destination": [ + "obj-47", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-47", + 0 + ], + "destination": [ + "obj-48", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-48", + 0 + ], + "destination": [ + "obj-49", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-49", + 0 + ], + "destination": [ + "obj-50", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-45", + 0 + ], + "destination": [ + "obj-52", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-52", + 0 + ], + "destination": [ + "obj-53", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-53", + 0 + ], + "destination": [ + "obj-54", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-53", + 3 + ], + "destination": [ + "obj-54", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-54", + 0 + ], + "destination": [ + "obj-55", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-55", + 1 + ], + "destination": [ + "obj-56", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-56", + 0 + ], + "destination": [ + "obj-57", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-57", + 0 + ], + "destination": [ + "obj-58", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-55", + 0 + ], + "destination": [ + "obj-58", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-58", + 0 + ], + "destination": [ + "obj-59", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-60", + 0 + ], + "destination": [ + "obj-61", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-61", + 1 + ], + "destination": [ + "obj-63", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-61", + 0 + ], + "destination": [ + "obj-62", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-63", + 0 + ], + "destination": [ + "obj-51", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-64", + 0 + ], + "destination": [ + "obj-65", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-65", + 0 + ], + "destination": [ + "obj-66", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-66", + 0 + ], + "destination": [ + "obj-67", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-67", + 0 + ], + "destination": [ + "obj-68", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-66", + 0 + ], + "destination": [ + "obj-69", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-69", + 0 + ], + "destination": [ + "obj-70", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-70", + 4 + ], + "destination": [ + "obj-14", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-70", + 3 + ], + "destination": [ + "obj-17", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-70", + 2 + ], + "destination": [ + "obj-20", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-70", + 1 + ], + "destination": [ + "obj-23", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-70", + 0 + ], + "destination": [ + "obj-71", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-71", + 0 + ], + "destination": [ + "obj-72", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-72", + 2 + ], + "destination": [ + "obj-26", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-72", + 1 + ], + "destination": [ + "obj-27", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-72", + 0 + ], + "destination": [ + "obj-73", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-73", + 0 + ], + "destination": [ + "obj-74", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-74", + 3 + ], + "destination": [ + "obj-28", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-74", + 2 + ], + "destination": [ + "obj-31", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-74", + 1 + ], + "destination": [ + "obj-34", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-74", + 0 + ], + "destination": [ + "obj-75", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-75", + 0 + ], + "destination": [ + "obj-76", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-76", + 2 + ], + "destination": [ + "obj-37", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-76", + 1 + ], + "destination": [ + "obj-38", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-76", + 0 + ], + "destination": [ + "obj-77", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-77", + 0 + ], + "destination": [ + "obj-78", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-78", + 3 + ], + "destination": [ + "obj-39", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-78", + 2 + ], + "destination": [ + "obj-42", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-78", + 1 + ], + "destination": [ + "obj-48", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-78", + 0 + ], + "destination": [ + "obj-79", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-79", + 0 + ], + "destination": [ + "obj-80", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-80", + 1 + ], + "destination": [ + "obj-51", + 0 + ] + } + } + ] + } +} diff --git a/runtime-tests/python/maxtest_editor.py b/runtime-tests/python/maxtest_editor.py index f868580..f09799f 100644 --- a/runtime-tests/python/maxtest_editor.py +++ b/runtime-tests/python/maxtest_editor.py @@ -24,6 +24,16 @@ def bump(self, name: str) -> None: source = re.sub(r"^REVISION = .*$", f"REVISION = {revision + 1}", source, count=1, flags=re.M) path.write_text(source, encoding="utf-8") + def reshape(self, name: str, inputs: int, outputs: int) -> None: + """Save the file as a class with `inputs` inputs and `outputs` outputs, each output passing the + input in its position (or silence): process() changes shape (plan 2.4).""" + parameters = "".join(f", x{i}: float" for i in range(inputs)) + values = [f"x{i}" if i < inputs else "0.0" for i in range(outputs)] + returns = "float" if outputs == 1 else "tuple[" + ", ".join(["float"] * outputs) + "]" + result = values[0] if outputs == 1 else "(" + ", ".join(values) + ")" + source = f"class {name}:\n def process(self{parameters}) -> {returns}:\n return {result}\n" + self._file(name).write_text(source, encoding="utf-8") + def remove_field(self, name: str, field: str) -> None: path = self._file(name) source = re.sub(rf"^\s+{field}: .*\n", "", path.read_text(encoding="utf-8"), count=1, flags=re.M) diff --git a/runtime-tests/python/maxtest_generator.py b/runtime-tests/python/maxtest_generator.py new file mode 100644 index 0000000..5f95c60 --- /dev/null +++ b/runtime-tests/python/maxtest_generator.py @@ -0,0 +1,9 @@ +# Runtime-test fixture (runtime-tests/run.py copies it into python/): process() with no inputs — +# a generator (plan 2.4). The object still has one inlet, for messages. + + +class maxtest_generator: + level: float = 0.25 + + def process(self) -> float: + return self.level diff --git a/runtime-tests/python/maxtest_shape.py b/runtime-tests/python/maxtest_shape.py new file mode 100644 index 0000000..91ecff6 --- /dev/null +++ b/runtime-tests/python/maxtest_shape.py @@ -0,0 +1,8 @@ +# Runtime-test fixture (runtime-tests/run.py copies it into python/): two inputs and two outputs, +# each passed through by position (plan 2.4). maxtest_editor's reshape() rewrites it with another +# number of each. + + +class maxtest_shape: + def process(self, x0: float, x1: float) -> tuple[float, float]: + return (x0, x1) diff --git a/source/projects/tap.python_tilde/tap.python_tilde.h b/source/projects/tap.python_tilde/tap.python_tilde.h index a056702..05de54d 100644 --- a/source/projects/tap.python_tilde/tap.python_tilde.h +++ b/source/projects/tap.python_tilde/tap.python_tilde.h @@ -41,15 +41,19 @@ class python : public object, public vector_operator<> { "messages called according to their signatures, with methods named int, float, symbol and " "bang answering those standard messages. Its process() method runs on the signal: once per " "signal vector when annotated with numpy arrays, or once per sample when annotated with " - "float. An optional prepare(sample_rate, vector_size) method receives the audio settings " + "float; its parameters are the object's signal inlets, and its return hint its outlets " + "(a tuple of values for more than one). An optional prepare(sample_rate, vector_size) " + "method receives the audio settings " "before audio starts and whenever they change. The file is watched and reloaded when saved, " "keeping attribute values; errors are printed to the Max console and never take Max down."}; MIN_TAGS{"programming"}; MIN_AUTHOR{"Tim Place"}; MIN_RELATED{"js, node.script"}; - inlet<> m_inlet{this, "(signal) input passed to the Python process() method"}; - outlet<> m_outlet_main{this, "(signal) output returned from the Python process() method", "signal"}; + // The first inlet and outlet; the constructor adds as many more as the class's process() + // declares (plan 2.4). + inlet<> m_inlet{this, "(signal) the first input to the Python process() method, and messages"}; + outlet<> m_outlet_main{this, "(signal) the first output returned from the Python process() method", "signal"}; argument m_source_arg{ this, "source", @@ -144,7 +148,11 @@ class python : public object, public vector_operator<> { m_python_source = "default"; } else { - m_python_source = to_string(args); + // the class file's name: one symbol, read as it is (anything else, as text, is not a + // valid name, and the core says so) + m_python_source = args.size() == 1 && c74::max::atom_gettype(&args[0]) == c74::max::A_SYM + ? std::string{c74::max::atom_getsym(&args[0])->s_name} + : to_string(args); } m_processor = std::make_unique( @@ -160,6 +168,7 @@ class python : public object, public vector_operator<> { reserved_messages(), [this] { m_reports.set(); }); update_source(); + create_ports(); // before min makes the Max inlets and outlets from its lists, after this // watch the source file for changes (delivered as our 'filechanged' message) — only a plain // file name: the core refuses anything else (e.g. "../x"), and so must the watcher @@ -194,6 +203,7 @@ class python : public object, public vector_operator<> { } create_attributes(); create_messages(); + report_ports(); } /// Dispatch a Max message to the bound Python method. @@ -290,6 +300,10 @@ class python : public object, public vector_operator<> { std::filesystem::path m_scripts_dir{}; std::unique_ptr m_file_watch; std::unique_ptr m_processor; + std::vector>> m_more_inlets; // after the first + std::vector>> m_more_outlets; // after the first + bool m_ports_made{}; + bool m_ports_differ{}; std::unordered_map> m_python_messages; std::unordered_map> m_python_attributes; @@ -359,6 +373,43 @@ class python : public object, public vector_operator<> { } } + /// A signal inlet for each input the class's process() declares, named for its parameter, and + /// an outlet for each output — at least one of each: the first inlet also takes messages. + /// Constructor only: min makes the Max inlets and outlets from these when it returns. + void create_ports() { + const auto& names = m_processor ? m_processor->input_names() : std::vector{}; + for (std::size_t i = 1; i < names.size(); ++i) { + m_more_inlets.push_back(std::make_unique>( + this, "(signal) " + names[i] + ": input " + std::to_string(i + 1) + " to the Python process() method")); + } + const std::size_t outputs = m_processor ? m_processor->output_count() : 1; + for (std::size_t i = 1; i < outputs; ++i) { + m_more_outlets.push_back(std::make_unique>( + this, "(signal) output " + std::to_string(i + 1) + " returned from the Python process() method", + "signal")); + } + m_ports_made = true; + } + + /// Say when a reload changed the inputs or outputs process() declares away from the inlets and + /// outlets this object was made with (once, until they match again). The core matches them: + /// a missing input reads as silence, an extra output is dropped. + void report_ports() { + if (!m_ports_made) { + return; + } + const auto inlets = 1 + m_more_inlets.size(); + const auto outlets = 1 + m_more_outlets.size(); + const auto inputs = std::max(1, m_processor->input_count()); + const auto outputs = m_processor->output_count(); + const bool differ = inputs != inlets || outputs != outlets; + if (differ && !m_ports_differ) { + cout << "process() now has " << inputs << " input(s) and " << outputs << " output(s); this object has " + << inlets << " inlet(s) and " << outlets << " outlet(s) — re-create it to change them" << endl; + } + m_ports_differ = differ; + } + /// Replace the previous incarnation's Max messages with the class's current methods. void create_messages() { for (auto& element : m_python_messages) { diff --git a/source/projects/tap.python_tilde/tap.python_tilde_test.cpp b/source/projects/tap.python_tilde/tap.python_tilde_test.cpp index 3bcda3c..28d6e01 100644 --- a/source/projects/tap.python_tilde/tap.python_tilde_test.cpp +++ b/source/projects/tap.python_tilde/tap.python_tilde_test.cpp @@ -8,8 +8,8 @@ // The mock kernel does not implement these Max functions, which the object // references for its dynamically generated attributes/messages and its file -// watcher. Provide inert stubs so the test binary links (the headers declare -// them with C linkage). With these stubs the Max-side attribute and method +// watcher, or implements one too thinly (attr_args_offset). Provide stubs so the +// test binary links (the headers declare them with C linkage). With these stubs the Max-side attribute and method // registrations fail harmlessly, so the tests below drive the object's own // attribute and message handlers directly, as Max's dispatch would. namespace c74 { @@ -36,6 +36,16 @@ namespace c74 { t_max_err object_method_typed(void*, t_symbol*, long, t_atom*, t_atom*) { return MAX_ERR_NONE; } + // The mock's says 0 — no arguments at all — so an object could not be given its class file. + // As the SDK documents it: how many atoms come before the first @attribute. + long attr_args_offset(short ac, t_atom* av) { + for (short i = 0; i < ac; ++i) { + if (atom_gettype(av + i) == A_SYM && atom_getsym(av + i)->s_name[0] == '@') { + return i; + } + } + return ac; + } void filewatcher_start(void*) {} void* qelem_new(void*, method) { static int s_qelem; @@ -217,3 +227,32 @@ SCENARIO("Messages reach the class's methods with their arguments converted") { } } } + +SCENARIO("The object has as many signal inlets and outlets as its class's process() declares (plan 2.4)") { + ext_main(nullptr); + // test_wrapper takes no arguments: make [tap.python~ stereo_width] as Max would + const auto argument = symbol_atom("stereo_width"); + auto* wrapped = c74::min::wrapper_new(c74::min::symbol("dummy"), 1, &argument); + REQUIRE(wrapped); + python& my_object = wrapped->m_min_object; + + THEN("two of each, the second inlet named for process()'s parameter") { + REQUIRE(my_object.inlets().size() == 2); + CHECK(my_object.outlets().size() == 2); + CHECK(my_object.inlets()[1]->description().find("right") != std::string::npos); + } + THEN("each channel is processed") { + std::vector left(64, 0.75); + std::vector right(64, 0.25); + std::vector out_left(64, 12345.0); + std::vector out_right(64, 12345.0); + double* in[2] = {left.data(), right.data()}; + double* out[2] = {out_left.data(), out_right.data()}; + audio_bundle input{in, 2, 64}; + audio_bundle output{out, 2, 64}; + my_object(input, output); + CHECK(all_equal(out_left, 0.75)); // width 1: as it was + CHECK(all_equal(out_right, 0.25)); + } + c74::max::object_free(wrapped); +} From 58e8e57c50891b60d917d856791a5317626a517e Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Wed, 30 Sep 2026 10:43:43 -0500 Subject: [PATCH 06/15] 2.4 (c): a save that changes process()'s shape changes the object's inlets 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) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- CHANGELOG.md | 4 +- ReadMe.md | 2 +- docs/PRODUCTION-PLAN.md | 16 +- runtime-tests/make_patchers.py | 22 +- .../tap.python~.channels.maxtest.maxpat | 2077 ++++++++++++----- .../tap.python_tilde/tap.python_tilde.h | 100 +- .../tap.python_tilde_test.cpp | 155 ++ 7 files changed, 1744 insertions(+), 632 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 82e7f8f..8274126 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,8 +14,8 @@ breaking changes to the contract are allowed where they buy correctness (D5 in `process(self) -> float` a generator (with one inlet still, for messages). The inputs are all `np.ndarray` or all per sample; a tuple return must say how many values it has. A return with the wrong number of values is output as silence and reported once. New example: `stereo_width.py`. - The object takes its inlets and outlets from the class when it is made; a save that changes how - many is reported, and takes effect when the object is re-created. (Plan 2.4.) *Changed with it:* + A save that changes how many changes the object's inlets and outlets in place, keeping the patch + cords of those that stay. (Plan 2.4.) *Changed with it:* `process()` taking `*args` is now reported and not bound (before, it was bound and its extra arguments never arrived). diff --git a/ReadMe.md b/ReadMe.md index 7f06f0b..5e8ea59 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -92,7 +92,7 @@ Python sources live in the package's `python` folder. `[tap.python~ name]` loads - `process(self, x: np.ndarray) -> np.ndarray` is called **once per signal vector** with a numpy array of the input and must return an array of the same length (any numeric dtype, or a list; it is converted). This is the form to use for anything that must run in real time — see `python/numpy_gain.py`, and `python/numpy_allpass.py` for a filter with feedback. The input array is reused from one call to the next: copy it if you want to keep it. - `process(self, x: float) -> float` is called **once per sample** — simplest for sketching; the call is cheap, but every line of Python in it runs once per sample (see [the performance note](#a-note-on-performance)). - Its parameters are the object's signal inlets and its return hint its outlets: `process(self, left: np.ndarray, right: np.ndarray) -> tuple[np.ndarray, np.ndarray]` makes an object with two of each (see `python/stereo_width.py`), and `process(self) -> float`, with no inputs, a generator — the first inlet is always there, for messages. The inputs are all `np.ndarray` or all per sample, and a tuple return must say how many values it has (`tuple[float, float]`). The object takes its inlets and outlets from the class when it is made; if a save changes how many, the console says so, and until the object is re-created an input it lacks reads as silence and an output it lacks is dropped. Wrap the object in `mc.` to run one instance per channel of a multichannel signal. Output that is not a number, or not finite (NaN, infinity), is replaced with 0.0 and reported once in the Max console, as is a return with the wrong number of values. + Its parameters are the object's signal inlets and its return hint its outlets: `process(self, left: np.ndarray, right: np.ndarray) -> tuple[np.ndarray, np.ndarray]` makes an object with two of each (see `python/stereo_width.py`), and `process(self) -> float`, with no inputs, a generator — the first inlet is always there, for messages. The inputs are all `np.ndarray` or all per sample, and a tuple return must say how many values it has (`tuple[float, float]`). A save that changes how many changes the object's inlets and outlets to match, keeping the patch cords of those that stay. Wrap the object in `mc.` to run one instance per channel of a multichannel signal. Output that is not a number, or not finite (NaN, infinity), is replaced with 0.0 and reported once in the Max console, as is a return with the wrong number of values. - **Audio settings** — an optional method `prepare(self, sample_rate: float, vector_size: int) -> None` is called with Max's sample rate and vector size before the object processes any audio, again whenever they change, and on every reload before the new code runs. `python/allpass.py` uses it to size its delay line. - **Hot reload** — saving the `.py` file reloads it in place, as a fresh module (names you deleted from the file are gone): the attributes and messages follow the new class, and audio resumes with the new code. Until the new code is ready the object keeps running the old one, so a successful reload swaps in without a gap in the audio. Attribute values carry over — set from the patcher or by your own code — for every attribute the new class still has with the same type; an attribute whose type changed starts from its new default, and one you removed disappears from the object. If the file has an error, the object prints the traceback to the Max console and outputs silence until the next successful reload (and the attribute values come back with it); a save that breaks a file shared by many objects is reported once, not by each, while an object created later with the file still broken says so again. Every object using the same file shares one execution of it per save, and the console says so once — `Loaded name.py: process() bound, one call per sample` (or per vector), from whichever object ran the file — along with anything true of the class, such as a method skipped for its name; a save that changes nothing reloads silently. Errors that belong to one object, such as an exception in its constructor, are still reported by each. Max's file watcher notices a save within a couple of seconds, but it coalesces saves made in quick succession — a script saving once a second, say — so the object then reloads for only some of them, and can lag behind until they stop; sending the object `filechanged` reloads it at once. - **Errors** — an exception raised by your code (in `process()`, a message, an attribute setter, the constructor or at import) prints its traceback to the Max console; it never takes Max down. That includes `sys.exit()`, which is reported like any other exception rather than quitting Max. diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index 6d9547c..cd2745d 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -100,8 +100,8 @@ while audio ran segfaulted in 5 of 5 runs. - [x] **2.3 `prepare(self, sample_rate, vector_size)`**, from min's `dspsetup`; also called on each newly loaded instance before it is published, so no vector ever runs on an unprepared instance. `allpass.py` uses it (and its α range is now open, per 5.4). -- [ ] **2.4 Multiple inlets/outlets** — `process` arguments define signal inlets and a tuple - return defines outlets, fixed at construction. *Decided (2026-09-30):* when a save changes the +- [x] **2.4 Multiple inlets/outlets** — `process` arguments define signal inlets and a tuple + return defines outlets. *Decided (2026-09-30):* when a save changes the counts, the object adapts its inlets and outlets in place with Max's dynamic inlets and outlets (`dynlet_begin`/`dynlet_end` around `dsp_resize` and `outlet_append`/`outlet_delete`, as Cycling '74 describes in its developer forum) rather than asking for the object to be @@ -119,7 +119,17 @@ while audio ran segfaulted in 5 of 5 runs. `[tap.python~ stereo_width]` has two of each and processes both (the test file now stands in a faithful `attr_args_offset`, and the object reads a one-symbol argument directly, not through `atom_gettext` — the mock's gives nothing); runtime test `channels` (stereo_width, a generator, a - save that changes the shape). *(c) adapting them on reload (dynlets).* + save that changes the shape). *(c) adapting them on reload (dynlets) — done:* after a reload that + changes the counts, `adapt_ports()` finds the object's box (`#B`) and, between `dynlet_begin` + and `dynlet_end`, sets the signal inlets with `dsp_resize` and deletes or appends outlets at the + end (`outlet_nth`/`outlet_delete`, `outlet_append`); min's own inlet and outlet lists follow at + once (its dsp64 reads a connection count for each, its assist the help text, now renamed with + the parameters on every reload); then `dspchain_setbroken(dspchain_fromobject())` has the signal + chain rebuilt. Without a box the object keeps its ports and says so, as in (b). Mock test: the + dynlet calls recorded against a pretend box, for a save that grows, shrinks, renames and breaks + the class; runtime test `channels`: grown from two to three, the old cords carry on and cords + that `thispatcher` connects to the new inlet and outlet carry signal (this check fails against + (b)); shrunk to one, the removed outlets' cords go with them. - [ ] **2.5 Worker mode (D1)** — `@mode worker`: Python on a worker thread, lock-free FIFO, latency reported to Max, underrun → silence. - [x] **2.6 Shorter reload stalls** — compile outside the swap and hold the GIL only for the swap. diff --git a/runtime-tests/make_patchers.py b/runtime-tests/make_patchers.py index 27803b7..f339679 100644 --- a/runtime-tests/make_patchers.py +++ b/runtime-tests/make_patchers.py @@ -561,17 +561,22 @@ def channels() -> Test: t = Test("tap.python~.channels.maxtest.maxpat", "Several inputs and outputs (plan 2.4): process()'s parameters are the object's signal inlets " "and its return hint its outlets — stereo_width's two of each, a generator's none (one inlet " - "still, for messages). A save that changes how many keeps the object's inlets and outlets " - "until it is re-created: a missing output is silent.") + "still, for messages). A save that changes how many changes the object's inlets and outlets " + "in place, keeping the patch cords of those that stay: new ones take cords and carry signal, " + "and the cords of those removed go with them.") left, right = t.signal(0.8), t.signal(0.2) width = t.obj("tap.python~ stereo_width", inlets=2, outlets=2, signal=True) t.patcher.connect(left, 0, width, 0) t.patcher.connect(right, 0, width, 1) generator = t.python("maxtest_generator") a, b = t.signal(0.3), t.signal(0.6) - shape = t.obj("tap.python~ maxtest_shape", inlets=2, outlets=2, signal=True) + # named, so that thispatcher can connect cords to the inlet and outlet a save adds + shape = t.patcher.box("tap.python~ maxtest_shape", 2, 2, column=2, outlettype=["signal"] * 2, varname="shape") t.patcher.connect(a, 0, shape, 0) t.patcher.connect(b, 0, shape, 1) + t.patcher.box("sig~ 0.9", 1, 1, column=2, outlettype=["signal"], varname="third_input") + third_output = t.patcher.box("+~ 0.", inlets=2, column=3, outlettype=["signal"], varname="third_output") + scripting = t.obj("thispatcher") editor = t.python("maxtest_editor", column=1) def outlet(box: str, n: int) -> str: # a box passing outlet n of `box` on, to sample @@ -589,9 +594,16 @@ def outlet(box: str, n: int) -> str: # a box passing outlet n of `box` on, to s t.step(t.sample_equals("mono-left-at-width-0", width_left, 0.5), t.sample_equals("mono-right-at-width-0", width_right, 0.5), t.sample_equals("generator-takes-messages", generator, 0.5)) + t.step(t.send("reshape maxtest_shape 3 3", editor), t.send("filechanged", shape)) + t.step(t.sample_equals("grown-keeps-first-cords", shape_first, 0.3), + t.sample_equals("grown-keeps-second-cords", shape_second, 0.6)) + t.step(t.send("script connect third_input 0 shape 2", scripting), + t.send("script connect shape 2 third_output 0", scripting)) + t.step(t.sample_equals("added-inlet-to-added-outlet", third_output, 0.9)) t.step(t.send("reshape maxtest_shape 1 1", editor), t.send("filechanged", shape)) - t.step(t.sample_equals("reshaped-first-output", shape_first, 0.3), - t.sample_equals("output-the-class-lost-is-silent", shape_second, 0.0), + t.step(t.sample_equals("shrunk-keeps-first-cords", shape_first, 0.3), + t.sample_equals("removed-outlet-takes-its-cord", shape_second, 0.0), + t.sample_equals("removed-outlets-take-their-cords", third_output, 0.0), t.errors_are("console-clean", "== 0"), wait=WATCH) return t diff --git a/runtime-tests/patchers/tap.python~.channels.maxtest.maxpat b/runtime-tests/patchers/tap.python~.channels.maxtest.maxpat index 60dd084..41c98d9 100644 --- a/runtime-tests/patchers/tap.python~.channels.maxtest.maxpat +++ b/runtime-tests/patchers/tap.python~.channels.maxtest.maxpat @@ -35,7 +35,7 @@ 480, 80.0 ], - "text": "tap.python~.channels\n\nSeveral inputs and outputs (plan 2.4): process()'s parameters are the object's signal inlets and its return hint its outlets \u2014 stereo_width's two of each, a generator's none (one inlet still, for messages). A save that changes how many keeps the object's inlets and outlets until it is re-created: a missing output is silent.", + "text": "tap.python~.channels\n\nSeveral inputs and outputs (plan 2.4): process()'s parameters are the object's signal inlets and its return hint its outlets \u2014 stereo_width's two of each, a generator's none (one inlet still, for messages). A save that changes how many changes the object's inlets and outlets in place, keeping the patch cords of those that stay: new ones take cords and carry signal, and the cords of those removed go with them.", "linecount": 4 } }, @@ -164,7 +164,8 @@ 191.0, 22.0 ], - "text": "tap.python~ maxtest_shape" + "text": "tap.python~ maxtest_shape", + "varname": "shape" } }, { @@ -177,12 +178,13 @@ "signal" ], "patching_rect": [ - 270.0, - 20.0, - 198.0, + 520.0, + 230.0, + 72.0, 22.0 ], - "text": "tap.python~ maxtest_editor" + "text": "sig~ 0.9", + "varname": "third_input" } }, { @@ -200,13 +202,50 @@ 51.0, 22.0 ], - "text": "+~ 0." + "text": "+~ 0.", + "varname": "third_output" } }, { "box": { "id": "obj-11", "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 520.0, + 260.0, + 93.0, + 22.0 + ], + "text": "thispatcher" + } + }, + { + "box": { + "id": "obj-12", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 270.0, + 20.0, + 198.0, + 22.0 + ], + "text": "tap.python~ maxtest_editor" + } + }, + { + "box": { + "id": "obj-13", + "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, "outlettype": [ @@ -223,7 +262,7 @@ }, { "box": { - "id": "obj-12", + "id": "obj-14", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -241,7 +280,7 @@ }, { "box": { - "id": "obj-13", + "id": "obj-15", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -259,7 +298,25 @@ }, { "box": { - "id": "obj-14", + "id": "obj-16", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 770.0, + 140.0, + 51.0, + 22.0 + ], + "text": "+~ 0." + } + }, + { + "box": { + "id": "obj-17", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -268,7 +325,7 @@ ], "patching_rect": [ 770.0, - 140.0, + 170.0, 177.0, 22.0 ], @@ -277,7 +334,7 @@ }, { "box": { - "id": "obj-15", + "id": "obj-18", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -286,7 +343,7 @@ ], "patching_rect": [ 770.0, - 170.0, + 200.0, 121.0, 22.0 ], @@ -295,7 +352,7 @@ }, { "box": { - "id": "obj-16", + "id": "obj-19", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -304,7 +361,7 @@ ], "patching_rect": [ 770.0, - 200.0, + 230.0, 254.0, 22.0 ], @@ -313,7 +370,7 @@ }, { "box": { - "id": "obj-17", + "id": "obj-20", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -322,7 +379,7 @@ ], "patching_rect": [ 770.0, - 230.0, + 260.0, 177.0, 22.0 ], @@ -331,7 +388,7 @@ }, { "box": { - "id": "obj-18", + "id": "obj-21", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -340,7 +397,7 @@ ], "patching_rect": [ 770.0, - 260.0, + 290.0, 121.0, 22.0 ], @@ -349,7 +406,7 @@ }, { "box": { - "id": "obj-19", + "id": "obj-22", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -358,7 +415,7 @@ ], "patching_rect": [ 770.0, - 290.0, + 320.0, 261.0, 22.0 ], @@ -367,7 +424,7 @@ }, { "box": { - "id": "obj-20", + "id": "obj-23", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -376,7 +433,7 @@ ], "patching_rect": [ 770.0, - 320.0, + 350.0, 177.0, 22.0 ], @@ -385,7 +442,7 @@ }, { "box": { - "id": "obj-21", + "id": "obj-24", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -394,7 +451,7 @@ ], "patching_rect": [ 770.0, - 350.0, + 380.0, 128.0, 22.0 ], @@ -403,7 +460,7 @@ }, { "box": { - "id": "obj-22", + "id": "obj-25", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -412,7 +469,7 @@ ], "patching_rect": [ 770.0, - 380.0, + 410.0, 268.0, 22.0 ], @@ -421,7 +478,7 @@ }, { "box": { - "id": "obj-23", + "id": "obj-26", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -430,7 +487,7 @@ ], "patching_rect": [ 770.0, - 410.0, + 440.0, 177.0, 22.0 ], @@ -439,7 +496,7 @@ }, { "box": { - "id": "obj-24", + "id": "obj-27", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -448,7 +505,7 @@ ], "patching_rect": [ 770.0, - 440.0, + 470.0, 121.0, 22.0 ], @@ -457,7 +514,7 @@ }, { "box": { - "id": "obj-25", + "id": "obj-28", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -466,7 +523,7 @@ ], "patching_rect": [ 770.0, - 470.0, + 500.0, 303.0, 22.0 ], @@ -475,7 +532,7 @@ }, { "box": { - "id": "obj-26", + "id": "obj-29", "maxclass": "message", "numinlets": 2, "numoutlets": 1, @@ -493,7 +550,7 @@ }, { "box": { - "id": "obj-27", + "id": "obj-30", "maxclass": "message", "numinlets": 2, "numoutlets": 1, @@ -511,7 +568,7 @@ }, { "box": { - "id": "obj-28", + "id": "obj-31", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -520,7 +577,7 @@ ], "patching_rect": [ 770.0, - 500.0, + 530.0, 177.0, 22.0 ], @@ -529,7 +586,7 @@ }, { "box": { - "id": "obj-29", + "id": "obj-32", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -538,7 +595,7 @@ ], "patching_rect": [ 770.0, - 530.0, + 560.0, 121.0, 22.0 ], @@ -547,7 +604,7 @@ }, { "box": { - "id": "obj-30", + "id": "obj-33", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -556,7 +613,7 @@ ], "patching_rect": [ 770.0, - 560.0, + 590.0, 240.0, 22.0 ], @@ -565,7 +622,7 @@ }, { "box": { - "id": "obj-31", + "id": "obj-34", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -574,7 +631,7 @@ ], "patching_rect": [ 770.0, - 590.0, + 620.0, 177.0, 22.0 ], @@ -583,7 +640,7 @@ }, { "box": { - "id": "obj-32", + "id": "obj-35", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -592,7 +649,7 @@ ], "patching_rect": [ 770.0, - 620.0, + 650.0, 121.0, 22.0 ], @@ -601,7 +658,7 @@ }, { "box": { - "id": "obj-33", + "id": "obj-36", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -610,7 +667,7 @@ ], "patching_rect": [ 770.0, - 650.0, + 680.0, 247.0, 22.0 ], @@ -619,7 +676,7 @@ }, { "box": { - "id": "obj-34", + "id": "obj-37", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -628,7 +685,7 @@ ], "patching_rect": [ 770.0, - 680.0, + 710.0, 177.0, 22.0 ], @@ -637,7 +694,7 @@ }, { "box": { - "id": "obj-35", + "id": "obj-38", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -646,7 +703,7 @@ ], "patching_rect": [ 770.0, - 710.0, + 740.0, 121.0, 22.0 ], @@ -655,7 +712,7 @@ }, { "box": { - "id": "obj-36", + "id": "obj-39", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -664,7 +721,7 @@ ], "patching_rect": [ 770.0, - 740.0, + 770.0, 268.0, 22.0 ], @@ -673,7 +730,7 @@ }, { "box": { - "id": "obj-37", + "id": "obj-40", "maxclass": "message", "numinlets": 2, "numoutlets": 1, @@ -686,12 +743,12 @@ 191.0, 22.0 ], - "text": "reshape maxtest_shape 1 1" + "text": "reshape maxtest_shape 3 3" } }, { "box": { - "id": "obj-38", + "id": "obj-41", "maxclass": "message", "numinlets": 2, "numoutlets": 1, @@ -709,7 +766,7 @@ }, { "box": { - "id": "obj-39", + "id": "obj-42", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -718,7 +775,7 @@ ], "patching_rect": [ 770.0, - 770.0, + 800.0, 177.0, 22.0 ], @@ -727,7 +784,7 @@ }, { "box": { - "id": "obj-40", + "id": "obj-43", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -736,7 +793,7 @@ ], "patching_rect": [ 770.0, - 800.0, + 830.0, 121.0, 22.0 ], @@ -745,7 +802,7 @@ }, { "box": { - "id": "obj-41", + "id": "obj-44", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -754,16 +811,16 @@ ], "patching_rect": [ 770.0, - 830.0, - 247.0, + 860.0, + 261.0, 22.0 ], - "text": "test.assert reshaped-first-output" + "text": "test.assert grown-keeps-first-cords" } }, { "box": { - "id": "obj-42", + "id": "obj-45", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -772,7 +829,7 @@ ], "patching_rect": [ 770.0, - 860.0, + 890.0, 177.0, 22.0 ], @@ -781,7 +838,7 @@ }, { "box": { - "id": "obj-43", + "id": "obj-46", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -790,16 +847,16 @@ ], "patching_rect": [ 770.0, - 890.0, + 920.0, 121.0, 22.0 ], - "text": "test.equals 0.0" + "text": "test.equals 0.6" } }, { "box": { - "id": "obj-44", + "id": "obj-47", "maxclass": "newobj", "numinlets": 1, "numoutlets": 1, @@ -808,73 +865,70 @@ ], "patching_rect": [ 770.0, - 920.0, - 317.0, + 950.0, + 268.0, 22.0 ], - "text": "test.assert output-the-class-lost-is-silent" + "text": "test.assert grown-keeps-second-cords" } }, { "box": { - "id": "obj-45", - "maxclass": "newobj", - "numinlets": 1, + "id": "obj-48", + "maxclass": "message", + "numinlets": 2, "numoutlets": 1, "outlettype": [ "" ], "patching_rect": [ - 1020.0, - 20.0, - 65.0, + 270.0, + 170.0, + 268.0, 22.0 ], - "text": "error 1" + "text": "script connect third_input 0 shape 2" } }, { "box": { - "id": "obj-46", - "maxclass": "newobj", - "numinlets": 1, + "id": "obj-49", + "maxclass": "message", + "numinlets": 2, "numoutlets": 1, "outlettype": [ "" ], "patching_rect": [ - 1020.0, - 50.0, - 40.0, + 270.0, + 200.0, + 275.0, 22.0 ], - "text": "t b" + "text": "script connect shape 2 third_output 0" } }, { "box": { - "id": "obj-47", + "id": "obj-50", "maxclass": "newobj", - "numinlets": 3, - "numoutlets": 4, + "numinlets": 1, + "numoutlets": 1, "outlettype": [ - "", - "", - "", "" ], "patching_rect": [ - 1020.0, - 80.0, - 135.0, + 770.0, + 980.0, + 177.0, 22.0 ], - "text": "counter 1 1000000" + "text": "test.sample~ @autorun 0" } }, { "box": { - "id": "obj-48", + "id": "obj-51", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -882,185 +936,143 @@ "" ], "patching_rect": [ - 1020.0, - 110.0, - 40.0, + 770.0, + 1010.0, + 121.0, 22.0 ], - "text": "i" + "text": "test.equals 0.9" } }, { "box": { - "id": "obj-49", + "id": "obj-52", "maxclass": "newobj", - "numinlets": 2, + "numinlets": 1, "numoutlets": 1, "outlettype": [ "" ], "patching_rect": [ - 1020.0, - 140.0, - 44.0, + 770.0, + 1040.0, + 289.0, 22.0 ], - "text": "== 0" + "text": "test.assert added-inlet-to-added-outlet" } }, { "box": { - "id": "obj-50", - "maxclass": "newobj", - "numinlets": 1, + "id": "obj-53", + "maxclass": "message", + "numinlets": 2, "numoutlets": 1, "outlettype": [ "" ], "patching_rect": [ - 770.0, - 950.0, + 270.0, + 230.0, 191.0, 22.0 ], - "text": "test.assert console-clean" - } - }, - { - "box": { - "id": "obj-51", - "maxclass": "newobj", - "numinlets": 1, - "numoutlets": 0, - "outlettype": [], - "patching_rect": [ - 20.0, - 108.0, - 114.0, - 22.0 - ], - "text": "test.terminate" + "text": "reshape maxtest_shape 1 1" } }, { "box": { - "id": "obj-52", - "maxclass": "newobj", - "numinlets": 1, + "id": "obj-54", + "maxclass": "message", + "numinlets": 2, "numoutlets": 1, "outlettype": [ "" ], "patching_rect": [ - 1020.0, - 170.0, - 72.0, + 270.0, + 260.0, + 93.0, 22.0 ], - "text": "tosymbol" + "text": "filechanged" } }, { "box": { - "id": "obj-53", + "id": "obj-55", "maxclass": "newobj", "numinlets": 1, - "numoutlets": 5, + "numoutlets": 1, "outlettype": [ - "", - "", - "", - "", "" ], "patching_rect": [ - 1020.0, - 200.0, + 770.0, + 1070.0, 177.0, 22.0 ], - "text": "regexp \\\" @substitute '" + "text": "test.sample~ @autorun 0" } }, { "box": { - "id": "obj-54", + "id": "obj-56", "maxclass": "newobj", - "numinlets": 1, + "numinlets": 2, "numoutlets": 1, "outlettype": [ "" ], "patching_rect": [ - 1020.0, - 230.0, - 86.0, + 770.0, + 1100.0, + 121.0, 22.0 ], - "text": "fromsymbol" + "text": "test.equals 0.3" } }, { "box": { - "id": "obj-55", + "id": "obj-57", "maxclass": "newobj", "numinlets": 1, - "numoutlets": 2, - "outlettype": [ - "", - "" - ], - "patching_rect": [ - 1020.0, - 260.0, - 51.0, - 22.0 - ], - "text": "t l b" - } - }, - { - "box": { - "id": "obj-56", - "maxclass": "newobj", - "numinlets": 3, - "numoutlets": 4, + "numoutlets": 1, "outlettype": [ - "", - "", - "", "" ], "patching_rect": [ - 1020.0, - 290.0, - 135.0, + 770.0, + 1130.0, + 268.0, 22.0 ], - "text": "counter 1 1000000" + "text": "test.assert shrunk-keeps-first-cords" } }, { "box": { - "id": "obj-57", + "id": "obj-58", "maxclass": "newobj", - "numinlets": 2, + "numinlets": 1, "numoutlets": 1, "outlettype": [ "" ], "patching_rect": [ - 1020.0, - 320.0, - 51.0, + 770.0, + 1160.0, + 177.0, 22.0 ], - "text": "<= 50" + "text": "test.sample~ @autorun 0" } }, { "box": { - "id": "obj-58", + "id": "obj-59", "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, @@ -1068,28 +1080,12 @@ "" ], "patching_rect": [ - 1020.0, - 350.0, - 72.0, - 22.0 - ], - "text": "gate 1 1" - } - }, - { - "box": { - "id": "obj-59", - "maxclass": "newobj", - "numinlets": 1, - "numoutlets": 0, - "outlettype": [], - "patching_rect": [ - 1020.0, - 380.0, - 170.0, + 770.0, + 1190.0, + 121.0, 22.0 ], - "text": "test.log console-error" + "text": "test.equals 0.0" } }, { @@ -1102,12 +1098,12 @@ "" ], "patching_rect": [ - 20.0, - 138.0, - 72.0, + 770.0, + 1220.0, + 303.0, 22.0 ], - "text": "loadbang" + "text": "test.assert removed-outlet-takes-its-cord" } }, { @@ -1115,54 +1111,53 @@ "id": "obj-61", "maxclass": "newobj", "numinlets": 1, - "numoutlets": 2, + "numoutlets": 1, "outlettype": [ - "", "" ], "patching_rect": [ - 20.0, - 168.0, - 51.0, + 770.0, + 1250.0, + 177.0, 22.0 ], - "text": "t b b" + "text": "test.sample~ @autorun 0" } }, { "box": { "id": "obj-62", - "maxclass": "message", + "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, "outlettype": [ "" ], "patching_rect": [ - 20.0, - 198.0, - 93.0, + 770.0, + 1280.0, + 121.0, 22.0 ], - "text": "; dsp start" + "text": "test.equals 0.0" } }, { "box": { "id": "obj-63", "maxclass": "newobj", - "numinlets": 2, + "numinlets": 1, "numoutlets": 1, "outlettype": [ "" ], "patching_rect": [ - 20.0, - 228.0, - 93.0, + 770.0, + 1310.0, + 324.0, 22.0 ], - "text": "delay 60000" + "text": "test.assert removed-outlets-take-their-cords" } }, { @@ -1170,112 +1165,110 @@ "id": "obj-64", "maxclass": "newobj", "numinlets": 1, - "numoutlets": 4, + "numoutlets": 1, "outlettype": [ - "", - "", - "", "" ], "patching_rect": [ + 1020.0, 20.0, - 258.0, - 79.0, + 65.0, 22.0 ], - "text": "dspstate~" + "text": "error 1" } }, { "box": { "id": "obj-65", "maxclass": "newobj", - "numinlets": 2, - "numoutlets": 2, + "numinlets": 1, + "numoutlets": 1, "outlettype": [ - "", "" ], "patching_rect": [ - 20.0, - 288.0, - 51.0, + 1020.0, + 50.0, + 40.0, 22.0 ], - "text": "sel 1" + "text": "t b" } }, { "box": { "id": "obj-66", "maxclass": "newobj", - "numinlets": 2, - "numoutlets": 2, + "numinlets": 3, + "numoutlets": 4, "outlettype": [ + "", + "", "", "" ], "patching_rect": [ - 20.0, - 318.0, - 79.0, + 1020.0, + 80.0, + 135.0, 22.0 ], - "text": "onebang 1" + "text": "counter 1 1000000" } }, { "box": { "id": "obj-67", - "maxclass": "message", + "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, "outlettype": [ "" ], "patching_rect": [ - 20.0, - 348.0, + 1020.0, + 110.0, 40.0, 22.0 ], - "text": "1" + "text": "i" } }, { "box": { "id": "obj-68", "maxclass": "newobj", - "numinlets": 1, + "numinlets": 2, "numoutlets": 1, "outlettype": [ "" ], "patching_rect": [ - 770.0, - 980.0, - 191.0, + 1020.0, + 140.0, + 44.0, 22.0 ], - "text": "test.assert audio-started" + "text": "== 0" } }, { "box": { "id": "obj-69", "maxclass": "newobj", - "numinlets": 2, + "numinlets": 1, "numoutlets": 1, "outlettype": [ "" ], "patching_rect": [ - 20.0, - 378.0, - 79.0, + 770.0, + 1340.0, + 191.0, 22.0 ], - "text": "delay 150" + "text": "test.assert console-clean" } }, { @@ -1283,39 +1276,33 @@ "id": "obj-70", "maxclass": "newobj", "numinlets": 1, - "numoutlets": 5, - "outlettype": [ - "", - "", - "", - "", - "" - ], + "numoutlets": 0, + "outlettype": [], "patching_rect": [ 20.0, - 408.0, - 93.0, + 108.0, + 114.0, 22.0 ], - "text": "t b b b b b" + "text": "test.terminate" } }, { "box": { "id": "obj-71", "maxclass": "newobj", - "numinlets": 2, + "numinlets": 1, "numoutlets": 1, "outlettype": [ "" ], "patching_rect": [ - 20.0, - 438.0, - 79.0, + 1020.0, + 170.0, + 72.0, 22.0 ], - "text": "delay 150" + "text": "tosymbol" } }, { @@ -1323,42 +1310,209 @@ "id": "obj-72", "maxclass": "newobj", "numinlets": 1, - "numoutlets": 3, + "numoutlets": 5, "outlettype": [ + "", + "", "", "", "" ], "patching_rect": [ - 20.0, - 468.0, - 65.0, - 22.0 - ], - "text": "t b b b" + 1020.0, + 200.0, + 177.0, + 22.0 + ], + "text": "regexp \\\" @substitute '" } }, { "box": { "id": "obj-73", "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 230.0, + 86.0, + 22.0 + ], + "text": "fromsymbol" + } + }, + { + "box": { + "id": "obj-74", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 1020.0, + 260.0, + 51.0, + 22.0 + ], + "text": "t l b" + } + }, + { + "box": { + "id": "obj-75", + "maxclass": "newobj", + "numinlets": 3, + "numoutlets": 4, + "outlettype": [ + "", + "", + "", + "" + ], + "patching_rect": [ + 1020.0, + 290.0, + 135.0, + 22.0 + ], + "text": "counter 1 1000000" + } + }, + { + "box": { + "id": "obj-76", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 320.0, + 51.0, + 22.0 + ], + "text": "<= 50" + } + }, + { + "box": { + "id": "obj-77", + "maxclass": "newobj", "numinlets": 2, "numoutlets": 1, "outlettype": [ "" ], + "patching_rect": [ + 1020.0, + 350.0, + 72.0, + 22.0 + ], + "text": "gate 1 1" + } + }, + { + "box": { + "id": "obj-78", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 0, + "outlettype": [], + "patching_rect": [ + 1020.0, + 380.0, + 170.0, + 22.0 + ], + "text": "test.log console-error" + } + }, + { + "box": { + "id": "obj-79", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], "patching_rect": [ 20.0, - 498.0, - 79.0, + 138.0, + 72.0, 22.0 ], - "text": "delay 150" + "text": "loadbang" } }, { "box": { - "id": "obj-74", + "id": "obj-80", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 168.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-81", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 198.0, + 93.0, + 22.0 + ], + "text": "; dsp start" + } + }, + { + "box": { + "id": "obj-82", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 228.0, + 93.0, + 22.0 + ], + "text": "delay 60000" + } + }, + { + "box": { + "id": "obj-83", "maxclass": "newobj", "numinlets": 1, "numoutlets": 4, @@ -1370,137 +1524,876 @@ ], "patching_rect": [ 20.0, - 528.0, + 258.0, 79.0, 22.0 ], - "text": "t b b b b" + "text": "dspstate~" + } + }, + { + "box": { + "id": "obj-84", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 288.0, + 51.0, + 22.0 + ], + "text": "sel 1" + } + }, + { + "box": { + "id": "obj-85", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 318.0, + 79.0, + 22.0 + ], + "text": "onebang 1" + } + }, + { + "box": { + "id": "obj-86", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 348.0, + 40.0, + 22.0 + ], + "text": "1" + } + }, + { + "box": { + "id": "obj-87", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 1370.0, + 191.0, + 22.0 + ], + "text": "test.assert audio-started" + } + }, + { + "box": { + "id": "obj-88", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 378.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-89", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 5, + "outlettype": [ + "", + "", + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 408.0, + 93.0, + 22.0 + ], + "text": "t b b b b b" + } + }, + { + "box": { + "id": "obj-90", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 438.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-91", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 3, + "outlettype": [ + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 468.0, + 65.0, + 22.0 + ], + "text": "t b b b" + } + }, + { + "box": { + "id": "obj-92", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 498.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-93", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 4, + "outlettype": [ + "", + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 528.0, + 79.0, + 22.0 + ], + "text": "t b b b b" + } + }, + { + "box": { + "id": "obj-94", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 558.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-95", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 3, + "outlettype": [ + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 588.0, + 65.0, + 22.0 + ], + "text": "t b b b" + } + }, + { + "box": { + "id": "obj-96", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 618.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-97", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 3, + "outlettype": [ + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 648.0, + 65.0, + 22.0 + ], + "text": "t b b b" + } + }, + { + "box": { + "id": "obj-98", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 678.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-99", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 3, + "outlettype": [ + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 708.0, + 65.0, + 22.0 + ], + "text": "t b b b" + } + }, + { + "box": { + "id": "obj-100", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 738.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-101", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 768.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-102", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 798.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-103", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 3, + "outlettype": [ + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 828.0, + 65.0, + 22.0 + ], + "text": "t b b b" + } + }, + { + "box": { + "id": "obj-104", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 858.0, + 86.0, + 22.0 + ], + "text": "delay 2500" + } + }, + { + "box": { + "id": "obj-105", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 5, + "outlettype": [ + "", + "", + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 888.0, + 93.0, + 22.0 + ], + "text": "t b b b b b" + } + }, + { + "box": { + "id": "obj-106", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 918.0, + 79.0, + 22.0 + ], + "text": "delay 500" + } + }, + { + "box": { + "id": "obj-107", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 948.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + } + ], + "lines": [ + { + "patchline": { + "source": [ + "obj-2", + 0 + ], + "destination": [ + "obj-4", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-3", + 0 + ], + "destination": [ + "obj-4", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-6", + 0 + ], + "destination": [ + "obj-8", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-7", + 0 + ], + "destination": [ + "obj-8", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-4", + 0 + ], + "destination": [ + "obj-13", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-4", + 1 + ], + "destination": [ + "obj-14", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-8", + 0 + ], + "destination": [ + "obj-15", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-8", + 1 + ], + "destination": [ + "obj-16", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-13", + 0 + ], + "destination": [ + "obj-17", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-17", + 0 + ], + "destination": [ + "obj-18", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-18", + 0 + ], + "destination": [ + "obj-19", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-14", + 0 + ], + "destination": [ + "obj-20", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-20", + 0 + ], + "destination": [ + "obj-21", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-21", + 0 + ], + "destination": [ + "obj-22", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-5", + 0 + ], + "destination": [ + "obj-23", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-23", + 0 + ], + "destination": [ + "obj-24", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-24", + 0 + ], + "destination": [ + "obj-25", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-16", + 0 + ], + "destination": [ + "obj-26", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-26", + 0 + ], + "destination": [ + "obj-27", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-27", + 0 + ], + "destination": [ + "obj-28", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-29", + 0 + ], + "destination": [ + "obj-4", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-30", + 0 + ], + "destination": [ + "obj-5", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-13", + 0 + ], + "destination": [ + "obj-31", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-31", + 0 + ], + "destination": [ + "obj-32", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-32", + 0 + ], + "destination": [ + "obj-33", + 0 + ] } }, { - "box": { - "id": "obj-75", - "maxclass": "newobj", - "numinlets": 2, - "numoutlets": 1, - "outlettype": [ - "" - ], - "patching_rect": [ - 20.0, - 558.0, - 79.0, - 22.0 + "patchline": { + "source": [ + "obj-14", + 0 ], - "text": "delay 150" + "destination": [ + "obj-34", + 0 + ] } }, { - "box": { - "id": "obj-76", - "maxclass": "newobj", - "numinlets": 1, - "numoutlets": 3, - "outlettype": [ - "", - "", - "" - ], - "patching_rect": [ - 20.0, - 588.0, - 65.0, - 22.0 + "patchline": { + "source": [ + "obj-34", + 0 ], - "text": "t b b b" + "destination": [ + "obj-35", + 0 + ] } }, { - "box": { - "id": "obj-77", - "maxclass": "newobj", - "numinlets": 2, - "numoutlets": 1, - "outlettype": [ - "" - ], - "patching_rect": [ - 20.0, - 618.0, - 86.0, - 22.0 + "patchline": { + "source": [ + "obj-35", + 0 ], - "text": "delay 2500" + "destination": [ + "obj-36", + 0 + ] } }, { - "box": { - "id": "obj-78", - "maxclass": "newobj", - "numinlets": 1, - "numoutlets": 4, - "outlettype": [ - "", - "", - "", - "" - ], - "patching_rect": [ - 20.0, - 648.0, - 79.0, - 22.0 + "patchline": { + "source": [ + "obj-5", + 0 ], - "text": "t b b b b" + "destination": [ + "obj-37", + 0 + ] } }, { - "box": { - "id": "obj-79", - "maxclass": "newobj", - "numinlets": 2, - "numoutlets": 1, - "outlettype": [ - "" + "patchline": { + "source": [ + "obj-37", + 0 ], - "patching_rect": [ - 20.0, - 678.0, - 79.0, - 22.0 + "destination": [ + "obj-38", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-38", + 0 ], - "text": "delay 500" + "destination": [ + "obj-39", + 0 + ] } }, { - "box": { - "id": "obj-80", - "maxclass": "newobj", - "numinlets": 1, - "numoutlets": 2, - "outlettype": [ - "", - "" + "patchline": { + "source": [ + "obj-40", + 0 ], - "patching_rect": [ - 20.0, - 708.0, - 51.0, - 22.0 + "destination": [ + "obj-12", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-41", + 0 ], - "text": "t b b" + "destination": [ + "obj-8", + 0 + ] } - } - ], - "lines": [ + }, { "patchline": { "source": [ - "obj-2", + "obj-15", 0 ], "destination": [ - "obj-4", + "obj-42", 0 ] } @@ -1508,23 +2401,23 @@ { "patchline": { "source": [ - "obj-3", + "obj-42", 0 ], "destination": [ - "obj-4", - 1 + "obj-43", + 0 ] } }, { "patchline": { "source": [ - "obj-6", + "obj-43", 0 ], "destination": [ - "obj-8", + "obj-44", 0 ] } @@ -1532,23 +2425,23 @@ { "patchline": { "source": [ - "obj-7", + "obj-16", 0 ], "destination": [ - "obj-8", - 1 + "obj-45", + 0 ] } }, { "patchline": { "source": [ - "obj-4", + "obj-45", 0 ], "destination": [ - "obj-10", + "obj-46", 0 ] } @@ -1556,11 +2449,11 @@ { "patchline": { "source": [ - "obj-4", - 1 + "obj-46", + 0 ], "destination": [ - "obj-11", + "obj-47", 0 ] } @@ -1568,11 +2461,11 @@ { "patchline": { "source": [ - "obj-8", + "obj-48", 0 ], "destination": [ - "obj-12", + "obj-11", 0 ] } @@ -1580,11 +2473,11 @@ { "patchline": { "source": [ - "obj-8", - 1 + "obj-49", + 0 ], "destination": [ - "obj-13", + "obj-11", 0 ] } @@ -1596,7 +2489,7 @@ 0 ], "destination": [ - "obj-14", + "obj-50", 0 ] } @@ -1604,11 +2497,11 @@ { "patchline": { "source": [ - "obj-14", + "obj-50", 0 ], "destination": [ - "obj-15", + "obj-51", 0 ] } @@ -1616,11 +2509,11 @@ { "patchline": { "source": [ - "obj-15", + "obj-51", 0 ], "destination": [ - "obj-16", + "obj-52", 0 ] } @@ -1628,11 +2521,11 @@ { "patchline": { "source": [ - "obj-11", + "obj-53", 0 ], "destination": [ - "obj-17", + "obj-12", 0 ] } @@ -1640,11 +2533,11 @@ { "patchline": { "source": [ - "obj-17", + "obj-54", 0 ], "destination": [ - "obj-18", + "obj-8", 0 ] } @@ -1652,11 +2545,11 @@ { "patchline": { "source": [ - "obj-18", + "obj-15", 0 ], "destination": [ - "obj-19", + "obj-55", 0 ] } @@ -1664,11 +2557,11 @@ { "patchline": { "source": [ - "obj-5", + "obj-55", 0 ], "destination": [ - "obj-20", + "obj-56", 0 ] } @@ -1676,11 +2569,11 @@ { "patchline": { "source": [ - "obj-20", + "obj-56", 0 ], "destination": [ - "obj-21", + "obj-57", 0 ] } @@ -1688,11 +2581,11 @@ { "patchline": { "source": [ - "obj-21", + "obj-16", 0 ], "destination": [ - "obj-22", + "obj-58", 0 ] } @@ -1700,11 +2593,11 @@ { "patchline": { "source": [ - "obj-13", + "obj-58", 0 ], "destination": [ - "obj-23", + "obj-59", 0 ] } @@ -1712,11 +2605,11 @@ { "patchline": { "source": [ - "obj-23", + "obj-59", 0 ], "destination": [ - "obj-24", + "obj-60", 0 ] } @@ -1724,11 +2617,11 @@ { "patchline": { "source": [ - "obj-24", + "obj-10", 0 ], "destination": [ - "obj-25", + "obj-61", 0 ] } @@ -1736,11 +2629,11 @@ { "patchline": { "source": [ - "obj-26", + "obj-61", 0 ], "destination": [ - "obj-4", + "obj-62", 0 ] } @@ -1748,11 +2641,11 @@ { "patchline": { "source": [ - "obj-27", + "obj-62", 0 ], "destination": [ - "obj-5", + "obj-63", 0 ] } @@ -1760,11 +2653,11 @@ { "patchline": { "source": [ - "obj-10", + "obj-64", 0 ], "destination": [ - "obj-28", + "obj-65", 0 ] } @@ -1772,11 +2665,11 @@ { "patchline": { "source": [ - "obj-28", + "obj-65", 0 ], "destination": [ - "obj-29", + "obj-66", 0 ] } @@ -1784,23 +2677,23 @@ { "patchline": { "source": [ - "obj-29", + "obj-66", 0 ], "destination": [ - "obj-30", - 0 + "obj-67", + 1 ] } }, { "patchline": { "source": [ - "obj-11", + "obj-67", 0 ], "destination": [ - "obj-31", + "obj-68", 0 ] } @@ -1808,11 +2701,11 @@ { "patchline": { "source": [ - "obj-31", + "obj-68", 0 ], "destination": [ - "obj-32", + "obj-69", 0 ] } @@ -1820,11 +2713,11 @@ { "patchline": { "source": [ - "obj-32", + "obj-64", 0 ], "destination": [ - "obj-33", + "obj-71", 0 ] } @@ -1832,11 +2725,11 @@ { "patchline": { "source": [ - "obj-5", + "obj-71", 0 ], "destination": [ - "obj-34", + "obj-72", 0 ] } @@ -1844,11 +2737,11 @@ { "patchline": { "source": [ - "obj-34", + "obj-72", 0 ], "destination": [ - "obj-35", + "obj-73", 0 ] } @@ -1856,11 +2749,11 @@ { "patchline": { "source": [ - "obj-35", - 0 + "obj-72", + 3 ], "destination": [ - "obj-36", + "obj-73", 0 ] } @@ -1868,11 +2761,11 @@ { "patchline": { "source": [ - "obj-37", + "obj-73", 0 ], "destination": [ - "obj-9", + "obj-74", 0 ] } @@ -1880,11 +2773,11 @@ { "patchline": { "source": [ - "obj-38", - 0 + "obj-74", + 1 ], "destination": [ - "obj-8", + "obj-75", 0 ] } @@ -1892,11 +2785,11 @@ { "patchline": { "source": [ - "obj-12", + "obj-75", 0 ], "destination": [ - "obj-39", + "obj-76", 0 ] } @@ -1904,11 +2797,11 @@ { "patchline": { "source": [ - "obj-39", + "obj-76", 0 ], "destination": [ - "obj-40", + "obj-77", 0 ] } @@ -1916,23 +2809,23 @@ { "patchline": { "source": [ - "obj-40", + "obj-74", 0 ], "destination": [ - "obj-41", - 0 + "obj-77", + 1 ] } }, { "patchline": { "source": [ - "obj-13", + "obj-77", 0 ], "destination": [ - "obj-42", + "obj-78", 0 ] } @@ -1940,11 +2833,11 @@ { "patchline": { "source": [ - "obj-42", + "obj-79", 0 ], "destination": [ - "obj-43", + "obj-80", 0 ] } @@ -1952,11 +2845,11 @@ { "patchline": { "source": [ - "obj-43", - 0 + "obj-80", + 1 ], "destination": [ - "obj-44", + "obj-82", 0 ] } @@ -1964,11 +2857,11 @@ { "patchline": { "source": [ - "obj-45", + "obj-80", 0 ], "destination": [ - "obj-46", + "obj-81", 0 ] } @@ -1976,11 +2869,11 @@ { "patchline": { "source": [ - "obj-46", + "obj-82", 0 ], "destination": [ - "obj-47", + "obj-70", 0 ] } @@ -1988,23 +2881,23 @@ { "patchline": { "source": [ - "obj-47", + "obj-83", 0 ], "destination": [ - "obj-48", - 1 + "obj-84", + 0 ] } }, { "patchline": { "source": [ - "obj-48", + "obj-84", 0 ], "destination": [ - "obj-49", + "obj-85", 0 ] } @@ -2012,11 +2905,11 @@ { "patchline": { "source": [ - "obj-49", + "obj-85", 0 ], "destination": [ - "obj-50", + "obj-86", 0 ] } @@ -2024,11 +2917,11 @@ { "patchline": { "source": [ - "obj-45", + "obj-86", 0 ], "destination": [ - "obj-52", + "obj-87", 0 ] } @@ -2036,11 +2929,11 @@ { "patchline": { "source": [ - "obj-52", + "obj-85", 0 ], "destination": [ - "obj-53", + "obj-88", 0 ] } @@ -2048,11 +2941,11 @@ { "patchline": { "source": [ - "obj-53", + "obj-88", 0 ], "destination": [ - "obj-54", + "obj-89", 0 ] } @@ -2060,11 +2953,11 @@ { "patchline": { "source": [ - "obj-53", - 3 + "obj-89", + 4 ], "destination": [ - "obj-54", + "obj-17", 0 ] } @@ -2072,11 +2965,11 @@ { "patchline": { "source": [ - "obj-54", - 0 + "obj-89", + 3 ], "destination": [ - "obj-55", + "obj-20", 0 ] } @@ -2084,11 +2977,11 @@ { "patchline": { "source": [ - "obj-55", - 1 + "obj-89", + 2 ], "destination": [ - "obj-56", + "obj-23", 0 ] } @@ -2096,11 +2989,11 @@ { "patchline": { "source": [ - "obj-56", - 0 + "obj-89", + 1 ], "destination": [ - "obj-57", + "obj-26", 0 ] } @@ -2108,11 +3001,11 @@ { "patchline": { "source": [ - "obj-57", + "obj-89", 0 ], "destination": [ - "obj-58", + "obj-90", 0 ] } @@ -2120,23 +3013,23 @@ { "patchline": { "source": [ - "obj-55", + "obj-90", 0 ], "destination": [ - "obj-58", - 1 + "obj-91", + 0 ] } }, { "patchline": { "source": [ - "obj-58", - 0 + "obj-91", + 2 ], "destination": [ - "obj-59", + "obj-29", 0 ] } @@ -2144,11 +3037,11 @@ { "patchline": { "source": [ - "obj-60", - 0 + "obj-91", + 1 ], "destination": [ - "obj-61", + "obj-30", 0 ] } @@ -2156,11 +3049,11 @@ { "patchline": { "source": [ - "obj-61", - 1 + "obj-91", + 0 ], "destination": [ - "obj-63", + "obj-92", 0 ] } @@ -2168,11 +3061,11 @@ { "patchline": { "source": [ - "obj-61", + "obj-92", 0 ], "destination": [ - "obj-62", + "obj-93", 0 ] } @@ -2180,11 +3073,11 @@ { "patchline": { "source": [ - "obj-63", - 0 + "obj-93", + 3 ], "destination": [ - "obj-51", + "obj-31", 0 ] } @@ -2192,11 +3085,11 @@ { "patchline": { "source": [ - "obj-64", - 0 + "obj-93", + 2 ], "destination": [ - "obj-65", + "obj-34", 0 ] } @@ -2204,11 +3097,11 @@ { "patchline": { "source": [ - "obj-65", - 0 + "obj-93", + 1 ], "destination": [ - "obj-66", + "obj-37", 0 ] } @@ -2216,11 +3109,11 @@ { "patchline": { "source": [ - "obj-66", + "obj-93", 0 ], "destination": [ - "obj-67", + "obj-94", 0 ] } @@ -2228,11 +3121,11 @@ { "patchline": { "source": [ - "obj-67", + "obj-94", 0 ], "destination": [ - "obj-68", + "obj-95", 0 ] } @@ -2240,11 +3133,11 @@ { "patchline": { "source": [ - "obj-66", - 0 + "obj-95", + 2 ], "destination": [ - "obj-69", + "obj-40", 0 ] } @@ -2252,11 +3145,11 @@ { "patchline": { "source": [ - "obj-69", - 0 + "obj-95", + 1 ], "destination": [ - "obj-70", + "obj-41", 0 ] } @@ -2264,11 +3157,11 @@ { "patchline": { "source": [ - "obj-70", - 4 + "obj-95", + 0 ], "destination": [ - "obj-14", + "obj-96", 0 ] } @@ -2276,11 +3169,11 @@ { "patchline": { "source": [ - "obj-70", - 3 + "obj-96", + 0 ], "destination": [ - "obj-17", + "obj-97", 0 ] } @@ -2288,11 +3181,11 @@ { "patchline": { "source": [ - "obj-70", + "obj-97", 2 ], "destination": [ - "obj-20", + "obj-42", 0 ] } @@ -2300,11 +3193,11 @@ { "patchline": { "source": [ - "obj-70", + "obj-97", 1 ], "destination": [ - "obj-23", + "obj-45", 0 ] } @@ -2312,11 +3205,11 @@ { "patchline": { "source": [ - "obj-70", + "obj-97", 0 ], "destination": [ - "obj-71", + "obj-98", 0 ] } @@ -2324,11 +3217,11 @@ { "patchline": { "source": [ - "obj-71", + "obj-98", 0 ], "destination": [ - "obj-72", + "obj-99", 0 ] } @@ -2336,11 +3229,11 @@ { "patchline": { "source": [ - "obj-72", + "obj-99", 2 ], "destination": [ - "obj-26", + "obj-48", 0 ] } @@ -2348,11 +3241,11 @@ { "patchline": { "source": [ - "obj-72", + "obj-99", 1 ], "destination": [ - "obj-27", + "obj-49", 0 ] } @@ -2360,11 +3253,11 @@ { "patchline": { "source": [ - "obj-72", + "obj-99", 0 ], "destination": [ - "obj-73", + "obj-100", 0 ] } @@ -2372,11 +3265,11 @@ { "patchline": { "source": [ - "obj-73", + "obj-100", 0 ], "destination": [ - "obj-74", + "obj-101", 0 ] } @@ -2384,11 +3277,11 @@ { "patchline": { "source": [ - "obj-74", - 3 + "obj-101", + 1 ], "destination": [ - "obj-28", + "obj-50", 0 ] } @@ -2396,23 +3289,11 @@ { "patchline": { "source": [ - "obj-74", - 2 - ], - "destination": [ - "obj-31", + "obj-101", 0 - ] - } - }, - { - "patchline": { - "source": [ - "obj-74", - 1 ], "destination": [ - "obj-34", + "obj-102", 0 ] } @@ -2420,11 +3301,11 @@ { "patchline": { "source": [ - "obj-74", + "obj-102", 0 ], "destination": [ - "obj-75", + "obj-103", 0 ] } @@ -2432,11 +3313,11 @@ { "patchline": { "source": [ - "obj-75", - 0 + "obj-103", + 2 ], "destination": [ - "obj-76", + "obj-53", 0 ] } @@ -2444,11 +3325,11 @@ { "patchline": { "source": [ - "obj-76", - 2 + "obj-103", + 1 ], "destination": [ - "obj-37", + "obj-54", 0 ] } @@ -2456,11 +3337,11 @@ { "patchline": { "source": [ - "obj-76", - 1 + "obj-103", + 0 ], "destination": [ - "obj-38", + "obj-104", 0 ] } @@ -2468,11 +3349,11 @@ { "patchline": { "source": [ - "obj-76", + "obj-104", 0 ], "destination": [ - "obj-77", + "obj-105", 0 ] } @@ -2480,11 +3361,11 @@ { "patchline": { "source": [ - "obj-77", - 0 + "obj-105", + 4 ], "destination": [ - "obj-78", + "obj-55", 0 ] } @@ -2492,11 +3373,11 @@ { "patchline": { "source": [ - "obj-78", + "obj-105", 3 ], "destination": [ - "obj-39", + "obj-58", 0 ] } @@ -2504,11 +3385,11 @@ { "patchline": { "source": [ - "obj-78", + "obj-105", 2 ], "destination": [ - "obj-42", + "obj-61", 0 ] } @@ -2516,11 +3397,11 @@ { "patchline": { "source": [ - "obj-78", + "obj-105", 1 ], "destination": [ - "obj-48", + "obj-67", 0 ] } @@ -2528,11 +3409,11 @@ { "patchline": { "source": [ - "obj-78", + "obj-105", 0 ], "destination": [ - "obj-79", + "obj-106", 0 ] } @@ -2540,11 +3421,11 @@ { "patchline": { "source": [ - "obj-79", + "obj-106", 0 ], "destination": [ - "obj-80", + "obj-107", 0 ] } @@ -2552,11 +3433,11 @@ { "patchline": { "source": [ - "obj-80", + "obj-107", 1 ], "destination": [ - "obj-51", + "obj-70", 0 ] } diff --git a/source/projects/tap.python_tilde/tap.python_tilde.h b/source/projects/tap.python_tilde/tap.python_tilde.h index 05de54d..5f3ae34 100644 --- a/source/projects/tap.python_tilde/tap.python_tilde.h +++ b/source/projects/tap.python_tilde/tap.python_tilde.h @@ -45,13 +45,15 @@ class python : public object, public vector_operator<> { "(a tuple of values for more than one). An optional prepare(sample_rate, vector_size) " "method receives the audio settings " "before audio starts and whenever they change. The file is watched and reloaded when saved, " - "keeping attribute values; errors are printed to the Max console and never take Max down."}; + "keeping attribute values; a save that changes process()'s inputs or outputs changes the " + "inlets and outlets to match, keeping the patch cords of those that stay. Errors are " + "printed to the Max console and never take Max down."}; MIN_TAGS{"programming"}; MIN_AUTHOR{"Tim Place"}; MIN_RELATED{"js, node.script"}; // The first inlet and outlet; the constructor adds as many more as the class's process() - // declares (plan 2.4). + // declares, and a reload changes them to match (plan 2.4). inlet<> m_inlet{this, "(signal) the first input to the Python process() method, and messages"}; outlet<> m_outlet_main{this, "(signal) the first output returned from the Python process() method", "signal"}; @@ -203,7 +205,7 @@ class python : public object, public vector_operator<> { } create_attributes(); create_messages(); - report_ports(); + adapt_ports(); } /// Dispatch a Max message to the bound Python method. @@ -377,24 +379,18 @@ class python : public object, public vector_operator<> { /// an outlet for each output — at least one of each: the first inlet also takes messages. /// Constructor only: min makes the Max inlets and outlets from these when it returns. void create_ports() { - const auto& names = m_processor ? m_processor->input_names() : std::vector{}; - for (std::size_t i = 1; i < names.size(); ++i) { - m_more_inlets.push_back(std::make_unique>( - this, "(signal) " + names[i] + ": input " + std::to_string(i + 1) + " to the Python process() method")); - } - const std::size_t outputs = m_processor ? m_processor->output_count() : 1; - for (std::size_t i = 1; i < outputs; ++i) { - m_more_outlets.push_back(std::make_unique>( - this, "(signal) output " + std::to_string(i + 1) + " returned from the Python process() method", - "signal")); - } + describe_ports(m_processor ? std::max(1, m_processor->input_count()) : 1, + m_processor ? m_processor->output_count() : 1); m_ports_made = true; } - /// Say when a reload changed the inputs or outputs process() declares away from the inlets and - /// outlets this object was made with (once, until they match again). The core matches them: - /// a missing input reads as silence, an extra output is dropped. - void report_ports() { + /// Make the inlets and outlets match what a reloaded class's process() declares, in place: + /// Max's dynamic inlets and outlets, changed between the box's dynlet_begin and dynlet_end, + /// keep the patch cords of every inlet and outlet that stays. The signal chain is then marked + /// broken, so it is rebuilt with the new counts. An object without a box (made by object_new) + /// keeps its ports and says so, once, until they match again; the core matches the channels: a + /// missing input reads as silence, an extra output is dropped. + void adapt_ports() { if (!m_ports_made) { return; } @@ -402,12 +398,70 @@ class python : public object, public vector_operator<> { const auto outlets = 1 + m_more_outlets.size(); const auto inputs = std::max(1, m_processor->input_count()); const auto outputs = m_processor->output_count(); - const bool differ = inputs != inlets || outputs != outlets; - if (differ && !m_ports_differ) { - cout << "process() now has " << inputs << " input(s) and " << outputs << " output(s); this object has " - << inlets << " inlet(s) and " << outlets << " outlet(s) — re-create it to change them" << endl; + if (inputs == inlets && outputs == outlets) { + describe_ports(inlets, outlets); // a parameter may have been renamed + m_ports_differ = false; + return; + } + + c74::max::t_object* box{}; + if (c74::max::object_obex_lookup(maxobj(), k_sym__pound_b, &box) != c74::max::MAX_ERR_NONE || !box) { + if (!m_ports_differ) { + cout << "process() now has " << inputs << " input(s) and " << outputs << " output(s); this object has " + << inlets << " inlet(s) and " << outlets << " outlet(s) — re-create it to change them" << endl; + } + describe_ports(inlets, outlets); + m_ports_differ = true; + return; + } + + c74::max::object_method(box, c74::max::gensym("dynlet_begin")); + c74::max::dsp_resize(reinterpret_cast(maxobj()), static_cast(inputs)); + for (auto n = outlets; n > outputs; --n) { + c74::max::outlet_delete(c74::max::outlet_nth(maxobj(), static_cast(n - 1))); + } + for (auto n = outlets; n < outputs; ++n) { + c74::max::outlet_append(maxobj(), nullptr, c74::max::gensym("signal")); + } + describe_ports(inputs, outputs); // min's lists follow Max's before anything can read them + c74::max::object_method(box, c74::max::gensym("dynlet_end")); + m_ports_differ = false; + + if (auto* chain = c74::max::dspchain_fromobject(maxobj())) { + c74::max::dspchain_setbroken(chain); + } + } + + /// min's lists of this object's inlets and outlets, one entry for each the Max object has: + /// min's dsp64 reads a connection count for each, and its assist the help text, which names + /// each inlet for its process() parameter. They make no Max inlets or outlets after the + /// constructor: the Max ones are made by min (at creation) or by adapt_ports(). + void describe_ports(const std::size_t inlet_count, const std::size_t outlet_count) { + auto& inlet_list = inlets(); + for (const auto& more : m_more_inlets) { + inlet_list.erase(std::remove(inlet_list.begin(), inlet_list.end(), more.get()), inlet_list.end()); + } + m_more_inlets.clear(); + const auto& names = m_processor ? m_processor->input_names() : std::vector{}; + for (std::size_t i = 1; i < inlet_count; ++i) { + const auto number = std::to_string(i + 1); + m_more_inlets.push_back(std::make_unique>( + this, i < names.size() + ? "(signal) " + names[i] + ": input " + number + " to the Python process() method" + : "(signal) input " + number + ": not used by the Python process() method")); + } + + auto& outlet_list = outlets(); + while (1 + m_more_outlets.size() > outlet_count && !m_more_outlets.empty()) { + const auto* last = m_more_outlets.back().get(); + outlet_list.erase(std::remove(outlet_list.begin(), outlet_list.end(), last), outlet_list.end()); + m_more_outlets.pop_back(); + } + while (1 + m_more_outlets.size() < outlet_count) { + const auto number = std::to_string(m_more_outlets.size() + 2); + m_more_outlets.push_back(std::make_unique>( + this, "(signal) output " + number + " returned from the Python process() method", "signal")); } - m_ports_differ = differ; } /// Replace the previous incarnation's Max messages with the class's current methods. diff --git a/source/projects/tap.python_tilde/tap.python_tilde_test.cpp b/source/projects/tap.python_tilde/tap.python_tilde_test.cpp index 28d6e01..2e76b5f 100644 --- a/source/projects/tap.python_tilde/tap.python_tilde_test.cpp +++ b/source/projects/tap.python_tilde/tap.python_tilde_test.cpp @@ -2,6 +2,9 @@ /// @copyright Copyright 2022-2026 Timothy Place. All rights reserved. /// @license Use of this source code is governed by the MIT License found in the License.md file. +#include +#include +#include #include #include "c74_min_unittest.h" // required unit-test header (defines main via Catch) @@ -60,6 +63,58 @@ namespace c74 { } // namespace max } // namespace c74 +// Max's dynamic inlets and outlets, which the mock kernel lacks: every object is in a pretend box, +// and what the object asks of it is recorded, so the tests can check what it does and that min's +// own lists follow. +namespace dynlets { + long signal_inlets{}; // the last dsp_resize, 0 if none + long appended{}; // outlets appended + std::vector deleted; // the indices of the outlets deleted, in order + bool chain_broken{}; + + void reset() { + signal_inlets = 0; + appended = 0; + deleted.clear(); + chain_broken = false; + } +} // namespace dynlets + +namespace c74 { + namespace max { + extern "C" { + t_max_err object_obex_lookup(void*, t_symbol* key, t_object** val) { + static int s_box; + if (key != gensym("#B")) { + return MAX_ERR_GENERIC; + } + *val = reinterpret_cast(&s_box); + return MAX_ERR_NONE; + } + void dsp_resize(t_pxobject*, long nsignals) { + dynlets::signal_inlets = nsignals; + } + void* outlet_append(t_object*, t_symbol*, t_symbol*) { + ++dynlets::appended; + return nullptr; + } + void* outlet_nth(t_object*, long n) { + return reinterpret_cast(static_cast(n + 1)); // never null + } + void outlet_delete(void* x) { + dynlets::deleted.push_back(static_cast(reinterpret_cast(x) - 1)); + } + t_dspchain* dspchain_fromobject(t_object*) { + static int s_chain; + return reinterpret_cast(&s_chain); + } + void dspchain_setbroken(t_dspchain*) { + dynlets::chain_broken = true; + } + } + } // namespace max +} // namespace c74 + #include "tap.python_tilde.cpp" // include the object source so we can instantiate it // The Max glue, end to end through the mock kernel. The test binary lands in /tests/, @@ -256,3 +311,103 @@ SCENARIO("The object has as many signal inlets and outlets as its class's proces } c74::max::object_free(wrapped); } + +namespace { + + /// A class with these process() parameters (per sample), returning this many values. + std::string shaped_class(const std::vector& inputs, const std::size_t outputs) { + std::string parameters; + std::string sum = "0.0"; + for (const auto& name : inputs) { + parameters += ", " + name + ": float"; + sum += " + " + name; + } + std::string hint = "float"; + std::string values = sum; + if (outputs > 1) { + hint = "tuple[float"; + for (std::size_t i = 1; i < outputs; ++i) { + hint += ", float"; + values += ", " + sum; + } + hint += "]"; + } + return "class maxtest_mock_shape:\n def process(self" + parameters + ") -> " + hint + ":\n return " + + values + "\n"; + } + + void write_file(const std::filesystem::path& path, const std::string& text) { + std::ofstream{path, std::ios::binary | std::ios::trunc} << text; + } + +} // namespace + +SCENARIO("A save that changes process()'s inputs or outputs changes the object's inlets and outlets in place " + "(plan 2.4)") { + ext_main(nullptr); + // a fixture in the package's python folder, where python/maxtest_*.py is ignored by git + const auto file = tap::python::package_root() / "python" / "maxtest_mock_shape.py"; + write_file(file, shaped_class({"left", "right"}, 2)); + const auto argument = symbol_atom("maxtest_mock_shape"); + auto* wrapped = c74::min::wrapper_new(c74::min::symbol("dummy"), 1, &argument); + REQUIRE(wrapped); + python& my_object = wrapped->m_min_object; + REQUIRE(my_object.inlets().size() == 2); + REQUIRE(my_object.outlets().size() == 2); + dynlets::reset(); + + WHEN("a save gives it three inputs and one output") { + write_file(file, shaped_class({"a", "b", "c"}, 1)); + my_object.update_source(); + THEN("Max's signal inlets become three and the last outlet is deleted") { + CHECK(dynlets::signal_inlets == 3); + CHECK(dynlets::deleted == std::vector{1}); + CHECK(dynlets::appended == 0); + CHECK(dynlets::chain_broken); + } + THEN("min's lists follow, each inlet named for its parameter") { + REQUIRE(my_object.inlets().size() == 3); + CHECK(my_object.outlets().size() == 1); + CHECK(my_object.inlets()[1]->description().find("b: input 2") != std::string::npos); + CHECK(my_object.inlets()[2]->description().find("c: input 3") != std::string::npos); + } + } + + WHEN("a save gives it no inputs and three outputs") { + write_file(file, shaped_class({}, 3)); + my_object.update_source(); + THEN("one signal inlet stays, for messages, and an outlet is appended") { + CHECK(dynlets::signal_inlets == 1); + CHECK(dynlets::appended == 1); + CHECK(dynlets::deleted.empty()); + CHECK(my_object.inlets().size() == 1); + CHECK(my_object.outlets().size() == 3); + } + } + + WHEN("a save renames an input but keeps the counts") { + write_file(file, shaped_class({"mid", "side"}, 2)); + my_object.update_source(); + THEN("Max's inlets and outlets are left alone, and the inlet's help names the new parameter") { + CHECK(dynlets::signal_inlets == 0); + CHECK(dynlets::appended == 0); + CHECK(dynlets::deleted.empty()); + CHECK_FALSE(dynlets::chain_broken); + REQUIRE(my_object.inlets().size() == 2); + CHECK(my_object.inlets()[1]->description().find("side: input 2") != std::string::npos); + } + } + + WHEN("a save breaks the class") { + write_file(file, "class maxtest_mock_shape:\n def process(self, x: float) -> float\n"); + my_object.update_source(); + THEN("the inlets and outlets stay as they were") { + CHECK(dynlets::signal_inlets == 0); + CHECK(my_object.inlets().size() == 2); + CHECK(my_object.outlets().size() == 2); + } + } + + c74::max::object_free(wrapped); + std::filesystem::remove(file); +} From a8d2e9866dc11cc088f92ca89dd74213632f7643 Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Wed, 30 Sep 2026 17:36:53 -0500 Subject: [PATCH 07/15] Package fixes from the first release (6.5); plan 4.7 (uv) and 4.8 (one package for every platform) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- .github/workflows/build.yml | 8 ++++++ docs/PRODUCTION-PLAN.md | 26 +++++++++++++++++++ scripts/assemble-package.py | 4 ++- .../projects/tap.python_tilde/CMakeLists.txt | 11 ++++++++ 4 files changed, 48 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index f895356..9a728c4 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -155,6 +155,14 @@ jobs: || { echo "ERROR: $bin is not universal"; exit 1; } done + # max-sdk-base leaves the identifier for Xcode to expand; the object's CMakeLists expands it + - name: Verify the bundle identifier is expanded + run: | + id=$(plutil -extract CFBundleIdentifier raw "externals/tap.python~.mxo/Contents/Info.plist") + echo "CFBundleIdentifier: $id" + [ "$id" = "com.74objects.tap.python-tilde" ] \ + || { echo "ERROR: expected com.74objects.tap.python-tilde"; exit 1; } + - name: Verify libpython resolves via a relative rpath only run: | bin="externals/tap.python~.mxo/Contents/MacOS/tap.python~" diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index cd2745d..c199088 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -238,6 +238,28 @@ while audio ran segfaulted in 5 of 5 runs. ships — Min-API, the Max SDK, CPython's, and each installed package's own (PEP 639 `dist-info/licenses/`, where numpy lists what it bundles) — with an index, collected from the package's actual contents; CI runs the collection on Linux. +- [ ] **4.7 uv for development and release tooling** — *Discussed (2026-09-30):* use uv where it + replaces work we do by hand; keep the shipped runtime a python-build-standalone archive pinned + by SHA256 in `runtime.lock`. For uv: `uv pip compile --universal --generate-hashes` in place of + most of `update-locks.py`'s PyPI handling; `uv pip install --python-platform --target …` + to install any platform's wheels from any machine (what 4.8 needs); `uv python install 3.13` for + the Linux fast loop's CPython with headers; `uv run` with inline script metadata for the + scripts. Against using it for the runtime: `uv python install` pins only through the uv + version, installs in its own layout, and may mark the interpreter externally managed (to + check) — and the work that matters (the `@rpath` install name, re-signing, the universal + libpython) is ours either way. Users never need uv; the ReadMe may mention + `uv pip install --python support/bin/python3 …` beside pip. +- [ ] **4.8 One package for every platform on each tag** — *Decided (2026-09-30):* a tag also + attaches a single `PythonTap-.zip` holding every platform's external and runtime, and + v0.x tags publish as pre-releases automatically (1.0 and later stay drafts until signing + exists). Needs one runtime per platform side by side — `support/macos-arm64/`, + `support/macos-x86_64/`, `support/windows-x64/` (one folder cannot hold both: Windows' `Lib/` + and the Mac's `lib/` collide on a case-insensitive disk) — with the macOS external choosing by + the architecture it runs as (each slice of the universal binary can carry its own rpath) and the + Windows external loading `python313.dll` from its folder by full path before the first + delay-loaded call (Max adds only `support/` itself to the DLL search path); and a last + `release.yml` job that merges the platform builds into one `PythonTap/` and attaches it with + its checksum (about 130 MB, against 37–55 MB per platform zip today). ## Phase 5 — documentation and examples @@ -367,6 +389,9 @@ passed; a third ran the soak (6.2) and measured performance (6.3). To continue: ReadMe promises (`release.yml` fixed; the draft's added by hand); the external's bundle identifier is min's template, unexpanded — `com.74objects.${PRODUCT_NAME:rfc1034identifier}` — to fix before signing and notarizing; and `docs/PRODUCTION-PLAN.md` ships inside the package. + *Both fixed since:* max-sdk-base leaves the identifier for Xcode to expand, which no other + generator does (every sibling Max package ships it the same way), so the object's CMakeLists + expands it — `com.74objects.tap.python-tilde`; `assemble-package.py` leaves the plan out. *Observed, not explained:* with the release installed, Max's file database took 8–11 minutes to report ready at each launch (seconds with the linked checkout; Max had also just been updated to 9.1.5 and rebuilt its database) — the runner no longer waits for it, as tests opened by name do @@ -431,6 +456,7 @@ passed; a third ran the soak (6.2) and measured performance (6.3). To continue: 7. Phase 4.5–4.6 — release packaging and licenses. 8. Phase 2.4–2.6 — multichannel, worker mode, reload stalls (features; may follow 1.0). 9. Phase 6 — in-Max validation before tagging 1.0. +10. Phase 4.7–4.8 — uv for the tooling, then one package for every platform on each tag. ## External prerequisites diff --git a/scripts/assemble-package.py b/scripts/assemble-package.py index eccb306..c0f7f36 100644 --- a/scripts/assemble-package.py +++ b/scripts/assemble-package.py @@ -44,7 +44,9 @@ # Never shipped from the copied folders. # maxtest_*.py: the runtime tests' fixtures, copied into python/ while runtime-tests/run.py runs -IGNORED = shutil.ignore_patterns("__pycache__", "*.pyc", ".ipynb_checkpoints", ".DS_Store", "maxtest_*") +# PRODUCTION-PLAN.md: the development roadmap in docs/, beside the reference page Max reads +IGNORED = shutil.ignore_patterns("__pycache__", "*.pyc", ".ipynb_checkpoints", ".DS_Store", "maxtest_*", + "PRODUCTION-PLAN.md") class AssemblyError(Exception): diff --git a/source/projects/tap.python_tilde/CMakeLists.txt b/source/projects/tap.python_tilde/CMakeLists.txt index d65081c..6147d7a 100644 --- a/source/projects/tap.python_tilde/CMakeLists.txt +++ b/source/projects/tap.python_tilde/CMakeLists.txt @@ -111,6 +111,17 @@ endif () include(${C74_MIN_API_DIR}/script/min-posttarget.cmake) # (C++20 is forced on this target and its test by the root CMakeLists.txt.) +if (APPLE) + # The bundle identifier: max-sdk-base leaves it as Xcode's ${PRODUCT_NAME:rfc1034identifier}, + # which only Xcode expands, so every other generator shipped it literally. Expand it here from + # the project name with the same rule — anything but letters, digits, '.' and '-' becomes '-': + # com.74objects.tap.python-tilde — for the Info.plist (configured from this variable when the + # build is generated) and for Xcode alike. + string(REGEX REPLACE "[^A-Za-z0-9.-]" "-" BUNDLE_IDENTIFIER "${PROJECT_NAME}") + set_target_properties(${PROJECT_NAME} PROPERTIES + XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER "${AUTHOR_DOMAIN}.${BUNDLE_IDENTIFIER}") +endif () + ############################################################# # UNIT TEST From 87a19bdbfc72f6f706cb3a82c2eaa0dffe61dbfe Mon Sep 17 00:00:00 2001 From: Timothy Place <109637+tap@users.noreply.github.com> Date: Wed, 30 Sep 2026 20:49:09 -0500 Subject: [PATCH 08/15] The reference page from Max: date the .mxo on each build (6.8) (#26) 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. --- CLAUDE.md | 5 +++-- docs/PRODUCTION-PLAN.md | 15 +++++++++++---- docs/tap.python~.maxref.xml | 2 +- runtime-tests/run.py | 6 ++++++ source/projects/tap.python_tilde/CMakeLists.txt | 6 ++++++ 5 files changed, 27 insertions(+), 7 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f686ca0..4f1032a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -144,8 +144,9 @@ the secrets exist, and attaches zips + SHA256s to a draft release. C++17), as TapTools-Max does. - **Keep in sync when behavior changes:** `ReadMe.md`, the object's min metadata (`MIN_DESCRIPTION`, argument and message descriptions — min regenerates - `docs/tap.python~.maxref.xml` from them whenever the external is newer, so never hand-edit the - page; commit the regenerated one), `help/tap.python~.maxhelp`, the examples and their notebook + `docs/tap.python~.maxref.xml` from them when Max loads an external newer than the page, so never + hand-edit the page: rebuild, run Max once — `runtime-tests/run.py` says when the page was + rewritten — and commit it), `help/tap.python~.maxhelp`, the examples and their notebook (committed executed), and the plan. - **Implement from documentation and published sources only** — the CPython C-API docs, the Max SDK docs — never by reverse-engineering another product. diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index c199088..094cca6 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -300,8 +300,8 @@ passed; a third ran the soak (6.2) and measured performance (6.3). To continue: only to check a universal build), then `cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build && ctest --test-dir build`. The external lands in `externals/`. When Max loads an external newer than `docs/tap.python~.maxref.xml`, min rewrites the page from the - object's metadata; the committed one was generated against the mock kernel, so if Max's - differs, commit Max's. (A symlinked package works for externals, but Max loads a package's + object's metadata (6.8: the build dates the `.mxo` for it, and `run.py` says when it happened); + commit Max's page when it differs. (A symlinked package works for externals, but Max loads a package's *extensions* only from a real folder — why `run.py` installs the harness as a copy.) 2. *5.2 — the help patcher.* Open `help/tap.python~.maxhelp`: its new boxes were added by hand (as JSON, in Max's layout), so check they sit sensibly and every message box works, then @@ -419,12 +419,19 @@ passed; a third ran the soak (6.2) and measured performance (6.3). To continue: nothing, and the external's own reload line is gone. Errors particular to an instance are unchanged. Pinned by a core test (two processors, a change, an unchanged reload) and a runtime test (five objects in Max: the class's diagnostic once per run of the file). -- [ ] **6.8 The reference page from Max** — runbook step 1 expects min to rewrite +- [x] **6.8 The reference page from Max** — runbook step 1 expects min to rewrite `docs/tap.python~.maxref.xml` when Max loads an external newer than it; in the Mac sessions it did not. Max's standard output had "file not found" and "failed to get date modified" lines at start-up — probably min's `doc_update` failing to resolve a path, not yet shown to come from this object. Find out why, and whether the committed page (generated against the mock kernel) is the - one Max would write. + one Max would write. *Done:* min's `doc_update` dates the external by its `.mxo` folder, and a + rebuild changes only the files inside it — the checkout's folder dated from its first build + (2026-08-05), older than the page, so the page never looked stale; a freshly unzipped release + has a new folder, which is why Max rewrote the installed package's page. The macOS build now + touches the folder after each link (a Windows `.mxe64` is one file, dated by its link already), + and `run.py` says when Max has rewritten the page, to commit it. Max's page matches the committed + one but for the description, which predated 2.4's text — now committed. The start-up lines are + not this object's: they still appear while its page is written. - [ ] **6.9 The help patcher and `numpy_allpass.py`** — the help patcher points to the `numpy_gain` and `allpass` examples but not to `numpy_allpass`, the one that shows what the block path is for; add it in Max (and re-save), perhaps with the measured comparison. diff --git a/docs/tap.python~.maxref.xml b/docs/tap.python~.maxref.xml index ab99833..6cc5050 100644 --- a/docs/tap.python~.maxref.xml +++ b/docs/tap.python~.maxref.xml @@ -7,7 +7,7 @@ Process audio with a Python class - Process audio with a Python class. The argument names a file in the package's python folder, which must define a class of the same name. The class's type-annotated public fields become attributes (int, float, bool and str; Optional allowed), and its public methods become messages called according to their signatures, with methods named int, float, symbol and bang answering those standard messages. Its process() method runs on the signal: once per signal vector when annotated with numpy arrays, or once per sample when annotated with float. An optional prepare(sample_rate, vector_size) method receives the audio settings before audio starts and whenever they change. The file is watched and reloaded when saved, keeping attribute values; errors are printed to the Max console and never take Max down. + Process audio with a Python class. The argument names a file in the package's python folder, which must define a class of the same name. The class's type-annotated public fields become attributes (int, float, bool and str; Optional allowed), and its public methods become messages called according to their signatures, with methods named int, float, symbol and bang answering those standard messages. Its process() method runs on the signal: once per signal vector when annotated with numpy arrays, or once per sample when annotated with float; its parameters are the object's signal inlets, and its return hint its outlets (a tuple of values for more than one). An optional prepare(sample_rate, vector_size) method receives the audio settings before audio starts and whenever they change. The file is watched and reloaded when saved, keeping attribute values; a save that changes process()'s inputs or outputs changes the inlets and outlets to match, keeping the patch cords of those that stay. Errors are printed to the Max console and never take Max down. diff --git a/runtime-tests/run.py b/runtime-tests/run.py index 5578a7c..e3ded73 100644 --- a/runtime-tests/run.py +++ b/runtime-tests/run.py @@ -58,6 +58,8 @@ SUPPORT = PACKAGE / "support" SUPPORT_ASIDE = PACKAGE / "support.maxtest-aside" EXTERNAL = PACKAGE / "externals" / "tap.python~.mxo" +# The reference page min rewrites from the object's descriptions (plan 6.8) +REFPAGE = ROOT / "docs" / "tap.python~.maxref.xml" OSCAR = HARNESS / "extensions" / "oscar.mxo" # Must match misc/max-test-config.json: Max listens on one port and sends to the other. @@ -556,6 +558,10 @@ def main() -> int: link.unlink(missing_ok=True) print() + if PACKAGE == ROOT and REFPAGE.exists() and subprocess.run( + ["git", "-C", str(ROOT), "diff", "--quiet", "--", str(REFPAGE)]).returncode == 1: + # min rewrites it when Max loads an external newer than it (plan 6.8) + print(f"Max rewrote {REFPAGE.relative_to(ROOT)} from the object's descriptions: review and commit it.") if failures: print(f"{len(failures)} failure(s):") for failure in failures: diff --git a/source/projects/tap.python_tilde/CMakeLists.txt b/source/projects/tap.python_tilde/CMakeLists.txt index 6147d7a..b35e712 100644 --- a/source/projects/tap.python_tilde/CMakeLists.txt +++ b/source/projects/tap.python_tilde/CMakeLists.txt @@ -120,6 +120,12 @@ if (APPLE) string(REGEX REPLACE "[^A-Za-z0-9.-]" "-" BUNDLE_IDENTIFIER "${PROJECT_NAME}") set_target_properties(${PROJECT_NAME} PROPERTIES XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER "${AUTHOR_DOMAIN}.${BUNDLE_IDENTIFIER}") + + # 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 (only files inside it + # change), so the page was never rewritten from a checkout (plan 6.8). Date the folder with + # each link. + add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD COMMAND touch "$") endif () From 53d0ed7a2203e51885dd82941066a4e1ee62d623 Mon Sep 17 00:00:00 2001 From: Timothy Place <109637+tap@users.noreply.github.com> Date: Wed, 30 Sep 2026 20:56:16 -0500 Subject: [PATCH 09/15] Help patcher: numpy_allpass, and inlets and outlets from process() (6.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. --- docs/PRODUCTION-PLAN.md | 8 ++++++-- help/tap.python~.maxhelp | 21 +++++++++++++++++---- 2 files changed, 23 insertions(+), 6 deletions(-) diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index 094cca6..313cec8 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -432,9 +432,13 @@ passed; a third ran the soak (6.2) and measured performance (6.3). To continue: and `run.py` says when Max has rewritten the page, to commit it. Max's page matches the committed one but for the description, which predated 2.4's text — now committed. The start-up lines are not this object's: they still appear while its page is written. -- [ ] **6.9 The help patcher and `numpy_allpass.py`** — the help patcher points to the `numpy_gain` +- [x] **6.9 The help patcher and `numpy_allpass.py`** — the help patcher points to the `numpy_gain` and `allpass` examples but not to `numpy_allpass`, the one that shows what the block path is for; - add it in Max (and re-save), perhaps with the measured comparison. + add it in Max (and re-save), perhaps with the measured comparison. *Done:* the examples note names + `numpy_allpass` as the same filter per vector, to swap in and watch the patcher's CPU meter (the + ReadMe's tables are the measured comparison); and a new note says what 2.4 made true — + `process()`'s parameters are the inlets, its return hint the outlets, `stereo_width` has two of + each, and a save that changes them changes the object. Checked open in Max 9.1.5. - [x] **6.10 One traceback per broken save** — a file that fails to load is not cached, so every object sharing it runs it and prints the traceback: 25 objects, 25 tracebacks. 6.7 left this alone, because the obvious fix — remember the failing source and stay quiet — would also hide diff --git a/help/tap.python~.maxhelp b/help/tap.python~.maxhelp index 411d714..41e1fcf 100644 --- a/help/tap.python~.maxhelp +++ b/help/tap.python~.maxhelp @@ -10,7 +10,7 @@ } , "classnamespace" : "box", - "rect" : [ 100.0, 100.0, 780.0, 600.0 ], + "rect" : [ 100.0, 100.0, 780.0, 650.0 ], "bglocked" : 0, "openinpresentation" : 0, "default_fontsize" : 13.0, @@ -351,17 +351,30 @@ "text" : "forces a reload; saving the file does it for you" } + } +, { + "box" : { + "fontsize" : 13.0, + "id" : "obj-41", + "linecount" : 4, + "maxclass" : "comment", + "numinlets" : 1, + "numoutlets" : 0, + "patching_rect" : [ 270.0, 510.0, 300.0, 76.0 ], + "text" : "process()'s parameters are the object's signal inlets and its return hint its outlets: [tap.python~ stereo_width] has two of each. A save that changes them changes the object's inlets and outlets." + } + } , { "box" : { "fontsize" : 13.0, "id" : "obj-37", - "linecount" : 6, + "linecount" : 9, "maxclass" : "comment", "numinlets" : 1, "numoutlets" : 0, - "patching_rect" : [ 20.0, 450.0, 235.0, 122.0 ], - "text" : "More examples in the python folder: [tap.python~ numpy_gain] processes a whole signal vector per call with numpy, the form to use when it has to run in real time; [tap.python~ allpass] is an allpass filter that sizes its delay line in prepare()." + "patching_rect" : [ 20.0, 450.0, 235.0, 180.0 ], + "text" : "More examples in the python folder: [tap.python~ numpy_gain] processes a whole signal vector per call with numpy, the form to use when it has to run in real time; [tap.python~ allpass] is an allpass filter that sizes its delay line in prepare(), and [tap.python~ numpy_allpass] the same filter per vector: swap one for the other and watch the CPU meter." } } From 76dc32babd17954f9718a83fd4d70069b0c06cf2 Mon Sep 17 00:00:00 2001 From: Timothy Place <109637+tap@users.noreply.github.com> Date: Wed, 30 Sep 2026 20:56:29 -0500 Subject: [PATCH 10/15] Plan: worker mode design (2.5), decided (#28) 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. --- docs/PRODUCTION-PLAN.md | 41 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index 313cec8..dbc421d 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -131,7 +131,46 @@ while audio ran segfaulted in 5 of 5 runs. that `thispatcher` connects to the new inlet and outlet carry signal (this check fails against (b)); shrunk to one, the removed outlets' cords go with them. - [ ] **2.5 Worker mode (D1)** — `@mode worker`: Python on a worker thread, lock-free FIFO, - latency reported to Max, underrun → silence. + latency reported to Max, underrun → silence. *Design (decided 2026-09-30):* + - **What it buys.** In direct mode the audio thread takes the GIL, so anything else holding it — + a reload compiling a large file (2.6's limit), a message handler, a GC pass — delays the + buffer. In worker mode the audio thread never takes the GIL or calls CPython: it copies + vectors in and out of a queue, and Python runs on a thread of its own, a fixed latency behind. + - **In the core** (D6), beside `processor`: a `worker` that owns the thread and a ring of slots, + each one vector of every host input and output channel. The audio thread writes vector *k*'s + inputs into a slot and reads vector *k − L*'s outputs; the worker takes slots in order and runs + the existing `processor::process()` on them — per sample or per vector, with 2.4's channel + matching — so the class contract does not change. Slot states are atomics (single producer, + single consumer, no locks); the audio thread wakes the worker with a C++20 atomic notify, which + never blocks. The worker's thread is created and joined on the main thread. + - **Latency** *L* is whole vectors, set by `@latency` (in vectors, default 2), and reported in + samples (*L* × vector size) by the read-only `@latencysamples`, which a patch can read to align + other paths. Max has no documented call for an MSP object to report latency to the host, so + none is used; the output is primed with *L* vectors of silence. + - **Underruns.** A slot not done when its outputs are due is output as silence and counted; the + worker still processes it when it gets there (so the class's state stays continuous) and + discards its outputs, catching up through the backlog, so the latency stays *L*. If it falls + a whole ring behind (the ring holds *L* + a margin), the oldest inputs are dropped, which the + class sees as a gap. Both are reported once per load from the main thread (`flush_reports()`), + never printed on the audio thread. + - **`prepare()` and the mode.** The ring is sized when the chain compiles (`dspsetup`: vector + size, and the object's inlet and outlet counts), with the worker stopped and restarted around + it; `prepare()` runs as now, on the main thread. `@mode` and `@latency` take effect at the next + compile — setting them marks the chain broken (as 2.4 does), so that is at once while audio + runs. + - **Reloads, attributes and messages** are unchanged: they take the GIL on the main or scheduler + thread, and the worker picks up a new binding at its next vector, as the audio thread does + now. An attribute change is heard *L* vectors later. + - **Tests.** Core battery (Linux, under TSan too): worker output equals direct output delayed by + *L* vectors, per sample and per vector, several channels; a worker stalled by a class that + sleeps underruns to silence, is reported once, and comes back at the same latency; reload + under a running worker; resizing in `prepare()`; destruction joins the thread. Runtime test in + Max: `@mode worker` against `delay~` of *L* vectors, a reload under audio, and + `@latencysamples`. + - **Decided:** latency in whole vectors, default 2; an underrun is silence with the latency kept; + one Python call per host vector — batching several per call would cut the per-call overhead + further (worker mode's other win) at more latency, a later option (`@block`) if measurements + show it pays. - [x] **2.6 Shorter reload stalls** — compile outside the swap and hold the GIL only for the swap. *Measured first* (`core/bench/reload_bench.cpp`: an audio thread with Core Audio's real-time scheduling computes 512-sample buffers of 64-sample vectors at 96 kHz while the main thread saves From 49fb308965f0be3a03249a12c181d2c4b71c6ade Mon Sep 17 00:00:00 2001 From: Timothy Place <109637+tap@users.noreply.github.com> Date: Wed, 30 Sep 2026 21:04:30 -0500 Subject: [PATCH 11/15] =?UTF-8?q?2.5=20(a):=20worker=20mode=20in=20the=20c?= =?UTF-8?q?ore=20=E2=80=94=20process()=20on=20a=20thread=20of=20its=20own?= =?UTF-8?q?=20(#29)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- CLAUDE.md | 4 +- core/CMakeLists.txt | 3 + core/include/tap/python/processor.h | 18 +- core/include/tap/python/worker.h | 333 ++++++++++++++++++++++++++++ core/tests/CMakeLists.txt | 1 + core/tests/python/stalls.py | 13 ++ core/tests/test_worker.cpp | 323 +++++++++++++++++++++++++++ docs/PRODUCTION-PLAN.md | 18 +- 8 files changed, 704 insertions(+), 9 deletions(-) create mode 100644 core/include/tap/python/worker.h create mode 100644 core/tests/python/stalls.py create mode 100644 core/tests/test_worker.cpp diff --git a/CLAUDE.md b/CLAUDE.md index 4f1032a..dd254cf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,7 +21,9 @@ its phases, and the audit findings behind them. Tick its items (with the PR) as signatures) that `processor.h` builds its descriptions from), `value.h` (the Max-atom value model and its coercion rules, which reproduce `atom_getlong`/`atom_getfloat`/`atom_getsym`), `processor.h` (load/reload, class introspection, attribute and message dispatch, `prepare()`, and `process()` — per sample, or - per vector when the input is hinted `np.ndarray` — plus `flush_reports()`). New CPython-facing + per vector when the input is hinted `np.ndarray` — plus `flush_reports()`), `worker.h` (worker + mode, plan 2.5: `process()` on a thread of its own, a fixed number of vectors behind an audio + thread that only copies through a lock-free ring and never takes the GIL). New CPython-facing behavior goes here, never in the wrapper. CMake target `tap::python` (`core/CMakeLists.txt`). - **`core/tests/`** — the core's Catch2 battery against CPython 3.13, with Python fixtures in `core/tests/python/` and the shipped examples copied alongside. Runs on Linux, including under diff --git a/core/CMakeLists.txt b/core/CMakeLists.txt index bfcf337..12501b6 100644 --- a/core/CMakeLists.txt +++ b/core/CMakeLists.txt @@ -16,6 +16,9 @@ add_library(tap::python ALIAS tap_python_core) # the family convention: tap add_library(tap::python_core ALIAS tap_python_core) # the original spelling, kept target_include_directories(tap_python_core INTERFACE "${CMAKE_CURRENT_SOURCE_DIR}/include") target_compile_features(tap_python_core INTERFACE cxx_std_20) +# worker.h runs process() on a std::thread (plan 2.5) +find_package(Threads REQUIRED) +target_link_libraries(tap_python_core INTERFACE Threads::Threads) if (CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR) enable_testing() diff --git a/core/include/tap/python/processor.h b/core/include/tap/python/processor.h index 917846e..29fdfa2 100644 --- a/core/include/tap/python/processor.h +++ b/core/include/tap/python/processor.h @@ -127,6 +127,10 @@ namespace tap::python { /// thread, after load(). const std::vector& input_names() const noexcept { return m_input_names; } + /// How many times load() has succeeded: what a host reporting once per load compares against + /// (worker mode does, plan 2.5). Any thread. + std::uint64_t load_count() const noexcept { return m_loads.load(std::memory_order_acquire); } + /// The most inputs, and the most outputs, a process() may declare. static constexpr std::size_t k_max_channels = 64; @@ -237,6 +241,7 @@ namespace tap::python { next.process_function = nullptr; next.prepare_function = nullptr; reset_warnings(); // each kind of audio-thread problem is reported once per load + m_loads.fetch_add(1, std::memory_order_release); release(previous); // may run finalizers, which may let other threads in: now safe if (executed) { @@ -528,12 +533,13 @@ namespace tap::python { std::vector m_attributes; std::vector m_messages; // The rest of the binding and the block buffer: read and written only under the GIL. - PyObject* m_prepare_function{}; // strong, or null - bool m_block_mode{}; - std::size_t m_inputs{1}; // the bound process()'s inputs and outputs - std::size_t m_outputs{1}; - std::vector m_input_names; // main thread only - bool m_announcing{}; // this load() ran the file: see announce() + PyObject* m_prepare_function{}; // strong, or null + bool m_block_mode{}; + std::size_t m_inputs{1}; // the bound process()'s inputs and outputs + std::size_t m_outputs{1}; + std::vector m_input_names; // main thread only + bool m_announcing{}; // this load() ran the file: see announce() + std::atomic m_loads{}; // successful load()s // The np.ndarray each input arrives in, reused every vector: strong, its buffer held so its // memory cannot move. struct block_buffer { diff --git a/core/include/tap/python/worker.h b/core/include/tap/python/worker.h new file mode 100644 index 0000000..64cbdfa --- /dev/null +++ b/core/include/tap/python/worker.h @@ -0,0 +1,333 @@ +/// @file worker.h +/// @brief Worker mode (plan 2.5): a processor's process() on a thread of its own, a fixed number of +/// vectors behind the audio thread, which never takes the GIL. +// SPDX-License-Identifier: MIT +// Copyright 2022-2026 Timothy Place. +// +// Host-independent. In direct mode the audio thread calls processor::process() and so takes the +// GIL: whatever else holds it — a reload compiling a large file, a message handler, a garbage +// collection — delays the audio. A worker moves that call to a thread of its own. The audio thread +// calls worker::process() once per vector, which copies the vector's inputs into a ring of slots +// and copies out the outputs of the vector `latency` vectors before it; the worker thread runs +// processor::process() on each slot in order — per sample or per vector, with the processor's +// channel matching — so the class contract does not change. The first `latency` vectors out are +// silence. +// +// A vector whose outputs are not ready when they are due (an underrun) is output as silence. The +// worker still processes it when it gets there, so the class sees every vector in order and the +// latency stays fixed; only that vector's output is lost. If the worker falls a whole ring behind +// (the latency plus a quarter of a second), the audio thread drops the inputs of new vectors until +// it catches up: the class sees a gap. Both are reported once per load, from the main thread +// (flush_reports()); the audio thread never prints, allocates, locks or calls Python. +// +// Threads: start(), stop(), flush_reports() and the destructor run on the host's main thread, +// never while it holds the GIL (stopping joins the worker, which may be waiting for it); process() +// on the audio thread, possibly at the same time as any of them (a host can run the old signal +// chain while it prepares the next). The audio thread borrows the ring for each vector by taking +// an atomic pointer, so start() and stop() wait at most one vector for it, and a vector that +// arrives while they hold it is silence. + +#pragma once + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include "tap/python/processor.h" + +namespace tap::python { + + class worker { + public: + /// The latency, in vectors, unless the host says otherwise. + static constexpr std::size_t k_default_latency = 2; + + /// @param target the processor to run; it must outlive the worker + /// @param log receives the worker's reports (main thread) + /// @param report_ready called on the audio thread when something needs reporting; the host + /// must then call flush_reports() from its main thread. Must be + /// real-time safe, as the processor's is (it may be the same callback). + explicit worker(processor& target, log_function log = {}, std::function report_ready = {}) + : m_target{target} + , m_log{std::move(log)} + , m_report_ready{std::move(report_ready)} {} + + ~worker() { stop(); } + + worker(const worker&) = delete; + worker& operator=(const worker&) = delete; + + /// Start the worker, or restart it with new settings: a ring for `inputs` and `outputs` host + /// channels of `vector_size` frames, `latency` vectors deep (at least 1), with room for the + /// worker to fall a quarter of a second behind at `sample_rate` (at least 16 vectors). + /// Whatever the previous worker had not processed is discarded. Main thread. + void start(const std::size_t inputs, const std::size_t outputs, const std::size_t vector_size, + const std::size_t latency, const double sample_rate) { + stop(); + const auto vectors = std::max(1, latency); + const auto frames = std::max(1, vector_size); + const auto backlog = + std::isfinite(sample_rate) && sample_rate > 0.0 + ? static_cast(std::ceil(k_backlog_seconds * sample_rate / static_cast(frames))) + : std::size_t{0}; + auto next = + std::make_unique(inputs, outputs, frames, vectors, vectors + std::max(k_min_backlog, backlog)); + ring* r = next.get(); + r->thread = std::thread{[this, r] { run(*r); }}; + m_owned = std::move(next); + m_latency = vectors * frames; + m_ring.store(r, std::memory_order_release); + } + + /// Stop the worker and join its thread; process() outputs silence until the next start(). + /// Main thread. + void stop() { + if (!m_owned) { + return; + } + // take the ring back from the audio thread, which holds it for one vector at most + ring* r = m_ring.exchange(nullptr, std::memory_order_acq_rel); + while (!r) { + std::this_thread::yield(); + r = m_ring.exchange(nullptr, std::memory_order_acq_rel); + } + r->stopping.store(true, std::memory_order_release); + r->signal.fetch_add(1, std::memory_order_release); + r->signal.notify_one(); + r->thread.join(); + m_owned.reset(); + m_latency = 0; + } + + /// True between start() and stop(). Main thread. + bool running() const noexcept { return m_owned != nullptr; } + + /// The latency in samples: the vectors it was started with times the vector size; 0 when + /// stopped. Main thread. + std::size_t latency_samples() const noexcept { return m_latency; } + + /// How many vectors the worker has processed (or passed over, dropped) since start(). Main + /// thread; for tests and diagnostics. + std::uint64_t processed() const noexcept { return m_owned ? m_owned->done.load(std::memory_order_acquire) : 0; } + + /// The audio thread's side, once per vector: queue this vector's inputs and output those of + /// the vector `latency` before (silence if the worker has not finished it). Inputs the host + /// does not give read as silence, outputs it does not take are dropped, and the class's + /// own matching applies on the worker. Never blocks, allocates, or takes the GIL. + void process(const double* const* inputs, const std::size_t input_count, double* const* outputs, + const std::size_t output_count, const std::size_t frame_count) { + ring* r = m_ring.exchange(nullptr, std::memory_order_acquire); + if (!r) { + silence(outputs, output_count, 0, frame_count); + return; + } + const auto frames = std::min(frame_count, r->vector_size); + + // this vector's inputs, unless the worker is a whole ring behind + const auto k = r->written.load(std::memory_order_relaxed); // written only here + if (k - r->done.load(std::memory_order_acquire) < r->slot_count) { + const auto index = k % r->slot_count; + for (std::size_t c = 0; c < r->inputs; ++c) { + double* to = r->input(index, c); + if (c < input_count && inputs[c]) { + std::copy_n(inputs[c], frames, to); + } + else { + std::fill_n(to, frames, 0.0); + } + } + r->slots[index].frames.store(frames, std::memory_order_relaxed); + r->slots[index].in_seq.store(k, std::memory_order_release); + } + else { + record(m_dropped, m_dropped_load); + } + r->written.store(k + 1, std::memory_order_release); + r->signal.fetch_add(1, std::memory_order_release); + r->signal.notify_one(); + + // the outputs of the vector `latency` before (the first `latency` vectors have none) + std::size_t given = 0; // frames of output given; the rest is silence + if (k >= r->latency) { + const auto m = k - r->latency; + const auto index = m % r->slot_count; + auto& slot = r->slots[index]; + if (r->done.load(std::memory_order_acquire) > m && slot.out_seq.load(std::memory_order_acquire) == m) { + given = std::min(slot.frames.load(std::memory_order_relaxed), frame_count); + for (std::size_t c = 0; c < output_count; ++c) { + if (c < r->outputs) { + std::copy_n(r->output(index, c), given, outputs[c]); + } + else { + std::fill_n(outputs[c], given, 0.0); + } + } + } + else if (slot.in_seq.load(std::memory_order_relaxed) == m) { + record(m_late, m_late_load); // its inputs were queued: the worker is late + } + } + silence(outputs, output_count, given, frame_count); + + m_ring.store(r, std::memory_order_release); + } + + /// Print what the audio thread recorded since the last flush: vectors output as silence + /// because the worker was late, and inputs dropped because it fell a whole ring behind. + /// Main thread. + void flush_reports() { + if (const auto late = m_late.exchange(0, std::memory_order_acq_rel); late != 0) { + log(log_level::error, "process() was late for " + std::to_string(late) + + " vector(s) in worker mode — output as silence, the latency kept " + "(reported once per load)"); + } + if (const auto dropped = m_dropped.exchange(0, std::memory_order_acq_rel); dropped != 0) { + log(log_level::error, "process() fell too far behind in worker mode — the input of " + + std::to_string(dropped) + + " vector(s) was dropped (reported once per load)"); + } + } + + private: + static constexpr std::uint64_t k_none = std::numeric_limits::max(); + static constexpr double k_backlog_seconds = 0.25; + static constexpr std::size_t k_min_backlog = 16; + + struct slot { + std::atomic in_seq{k_none}; // the vector whose inputs it holds + std::atomic out_seq{k_none}; // the vector whose outputs it holds + std::atomic frames{}; + }; + + /// One run of the worker: the slots, and the thread that processes them. + struct ring { + ring(const std::size_t input_channels, const std::size_t output_channels, const std::size_t frames, + const std::size_t vectors, const std::size_t count) + : inputs{input_channels} + , outputs{output_channels} + , vector_size{frames} + , latency{vectors} + , slot_count{count} + , input_samples(count * input_channels * frames) + , output_samples(count * output_channels * frames) + , slots(count) {} + + double* input(const std::size_t index, const std::size_t channel) { + return input_samples.data() + ((index * inputs) + channel) * vector_size; + } + double* output(const std::size_t index, const std::size_t channel) { + return output_samples.data() + ((index * outputs) + channel) * vector_size; + } + + std::size_t inputs; + std::size_t outputs; + std::size_t vector_size; + std::size_t latency; + std::size_t slot_count; + std::vector input_samples; + std::vector output_samples; + std::vector slots; + std::atomic written{}; // vectors the audio thread has queued + std::atomic done{}; // vectors the worker has finished (or passed over) + std::atomic signal{}; // bumped to wake the worker + std::atomic stopping{}; + std::thread thread; + }; + + processor& m_target; + log_function m_log; + std::function m_report_ready; + + std::atomic m_ring{}; // the running ring, while the audio thread is not using it + std::unique_ptr m_owned; // the running ring (main thread) + std::size_t m_latency{}; // in samples (main thread) + + std::atomic m_late{}; // vectors output as silence since the last flush + std::atomic m_dropped{}; // vectors whose inputs were dropped + std::atomic m_late_load{k_none}; // the load for which late vectors were last reported + std::atomic m_dropped_load{k_none}; // the same, for dropped ones + + /// The worker thread: process each queued vector in order, sleeping while there is none. + void run(ring& r) { + std::vector in(r.inputs); + std::vector out(r.outputs); + std::uint64_t next = 0; + for (;;) { + const auto signalled = r.signal.load(std::memory_order_acquire); + if (r.stopping.load(std::memory_order_acquire)) { + return; + } + if (next == r.written.load(std::memory_order_acquire)) { + r.signal.wait(signalled, std::memory_order_acquire); + continue; + } + const auto index = next % r.slot_count; + auto& slot = r.slots[index]; + if (slot.in_seq.load(std::memory_order_acquire) == next) { // not dropped + for (std::size_t c = 0; c < r.inputs; ++c) { + in[c] = r.input(index, c); + } + for (std::size_t c = 0; c < r.outputs; ++c) { + out[c] = r.output(index, c); + } + const auto frames = slot.frames.load(std::memory_order_relaxed); + try { + m_target.process(in.data(), r.inputs, out.data(), r.outputs, frames); + } + catch (...) { // an exception must not end the thread (and with it, the host) + silence(out.data(), r.outputs, 0, frames); + } + slot.out_seq.store(next, std::memory_order_release); + } + ++next; + r.done.store(next, std::memory_order_release); + } + } + + /// Count one late or dropped vector (audio thread), and ask for a report if it is the first + /// since the class was last loaded; later ones are counted into that report until it is + /// flushed, and then not again until the next load. + void record(std::atomic& count, std::atomic& reported_load) { + const auto load = m_target.load_count(); + if (reported_load.load(std::memory_order_relaxed) == load) { + // reported already: count it into the report if that is still pending (never into one + // flushed meanwhile, which would carry it over to the next load's) + auto pending = count.load(std::memory_order_relaxed); + while (pending != 0 && !count.compare_exchange_weak(pending, pending + 1, std::memory_order_relaxed)) { + } + return; + } + reported_load.store(load, std::memory_order_relaxed); + count.fetch_add(1, std::memory_order_release); + if (m_report_ready) { + m_report_ready(); + } + } + + void log(const log_level level, const std::string& text) const { + if (m_log) { + m_log(level, text); + } + } + + /// Zero `count` channels of `out` from `first_frame` to `frame_count`. + static void silence(double* const* out, const std::size_t count, const std::size_t first_frame, + const std::size_t frame_count) { + for (std::size_t c = 0; c < count; ++c) { + if (first_frame < frame_count) { + std::fill(out[c] + first_frame, out[c] + frame_count, 0.0); + } + } + } + }; + +} // namespace tap::python diff --git a/core/tests/CMakeLists.txt b/core/tests/CMakeLists.txt index 30d74d4..380a962 100644 --- a/core/tests/CMakeLists.txt +++ b/core/tests/CMakeLists.txt @@ -35,6 +35,7 @@ add_executable(tap_python_core_tests test_loading.cpp test_types.cpp test_channels.cpp + test_worker.cpp ) target_link_libraries(tap_python_core_tests PRIVATE tap::python Python3::Python Catch2::Catch2WithMain) diff --git a/core/tests/python/stalls.py b/core/tests/python/stalls.py new file mode 100644 index 0000000..2c3d3b9 --- /dev/null +++ b/core/tests/python/stalls.py @@ -0,0 +1,13 @@ +# Test fixture: a process() that can be told to stall once, as a worker falling behind (plan 2.5). +# Identity otherwise, so each output sample says which input it came from. +import time + + +class stalls: + stall: float = 0.0 # seconds to sleep at the next sample, once + + def process(self, x: float) -> float: + if self.stall: + seconds, self.stall = self.stall, 0.0 + time.sleep(seconds) + return x diff --git a/core/tests/test_worker.cpp b/core/tests/test_worker.cpp new file mode 100644 index 0000000..b34e825 --- /dev/null +++ b/core/tests/test_worker.cpp @@ -0,0 +1,323 @@ +/// @file test_worker.cpp +/// @brief Worker mode (plan 2.5): process() on a thread of its own, a fixed latency behind the +/// audio thread. +// SPDX-License-Identifier: MIT +// Copyright 2022-2026 Timothy Place. + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include + +#include "support.h" +#include "tap/python/worker.h" + +using namespace tap::python; +using namespace tap::python::test; + +namespace { + + constexpr std::size_t k_frames = 64; + + using channel_data = std::vector>; + + /// A processor run by a worker, with one counter for both's report_ready. + struct harness { + log_capture log; + std::atomic notified{0}; + processor p; + worker w; // declared after p: stopped (and joined) before p goes + + explicit harness(const char* name) + : p{name, log.sink(), {}, [this] { ++notified; }} + , w{p, log.sink(), [this] { ++notified; }} {} + + /// One vector through the worker, as the audio thread calls it: each input channel holds + /// one value throughout; returns `output_count` channels. + channel_data push(const std::vector& values, const std::size_t output_count, + const std::size_t frame_count = k_frames) { + channel_data inputs; + channel_data outputs(output_count, std::vector(frame_count, 12345.0)); + std::vector in; + std::vector out; + for (const auto v : values) { + inputs.emplace_back(frame_count, v); + } + for (const auto& channel : inputs) { + in.push_back(channel.data()); + } + for (auto& channel : outputs) { + out.push_back(channel.data()); + } + w.process(in.data(), in.size(), out.data(), out.size(), frame_count); + return outputs; + } + + /// Wait until the worker has processed `count` vectors (a test may wait; the audio thread + /// never does). + void wait_for(const std::uint64_t count) { + const auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds{20}; + while (w.processed() < count && std::chrono::steady_clock::now() < deadline) { + std::this_thread::sleep_for(std::chrono::microseconds{100}); + } + REQUIRE(w.processed() >= count); + } + + std::size_t lines_containing(const std::string& fragment) const { + const auto lines = log.lines(); + return static_cast(std::count_if(lines.begin(), lines.end(), [&](const auto& line) { + return line.text.find(fragment) != std::string::npos; + })); + } + }; + + bool numpy_importable() { + gil_lock lock; + PyObject* numpy = PyImport_ImportModule("numpy"); + if (!numpy) { + PyErr_Clear(); + } + Py_XDECREF(numpy); + if (std::getenv("TAP_PYTHON_TEST_REQUIRE_EXAMPLES")) { + REQUIRE(numpy != nullptr); + } + return numpy != nullptr; + } + +} // namespace + +SCENARIO("In worker mode the output is the direct output, the latency later (plan 2.5)") { + ensure_runtime(); + const auto [name, block] = GENERATE(std::pair{"two_by_two", false}, std::pair{"block_two_by_two", true}); + if (block && !numpy_importable()) { + SKIP("numpy is not importable by the embedded interpreter"); + } + const std::size_t latency = GENERATE(1, 2, 3); + harness h{name}; + REQUIRE(h.p.load()); + h.p.prepare(48000.0, k_frames); + h.w.start(2, 2, k_frames, latency, 48000.0); + CHECK(h.w.running()); + CHECK(h.w.latency_samples() == latency * k_frames); + + for (std::size_t k = 0; k < 12; ++k) { + const auto a = static_cast(k + 1); + const auto outputs = h.push({a, a / 4.0}, 2); + h.wait_for(k + 1); + if (k < latency) { + CHECK(all_equal(outputs[0], 0.0)); // the first `latency` vectors are silence + CHECK(all_equal(outputs[1], 0.0)); + } + else { + const auto was = static_cast(k - latency + 1); // vector k - latency's input + CHECK(all_equal(outputs[0], was * 1.25)); + CHECK(all_equal(outputs[1], was * 0.75)); + } + } + CHECK(h.notified.load() == 0); +} + +SCENARIO("The host's channels are matched to the worker's ring (plan 2.5)") { + ensure_runtime(); + harness h{"two_by_two"}; + REQUIRE(h.p.load()); + h.w.start(2, 2, k_frames, 1, 48000.0); + + WHEN("the host gives one input and takes three outputs") { + h.push({2.0}, 3); + h.wait_for(1); + const auto outputs = h.push({2.0}, 3); + THEN("the missing input is silence and the extra output silent") { + CHECK(all_equal(outputs[0], 2.0)); // 2 + 0 + CHECK(all_equal(outputs[1], 2.0)); // 2 - 0 + CHECK(all_equal(outputs[2], 0.0)); + } + } + WHEN("the host gives a shorter vector") { + h.push({1.0, 1.0}, 2, 16); + h.wait_for(1); + const auto outputs = h.push({1.0, 1.0}, 2, 16); + THEN("that many frames come back") { + CHECK(all_equal(outputs[0], 2.0)); + } + } +} + +SCENARIO("A worker that falls behind outputs silence, keeps its latency, and says so once per load " + "(plan 2.5)") { + ensure_runtime(); + harness h{"stalls"}; + REQUIRE(h.p.load()); + h.w.start(1, 1, k_frames, 2, 48000.0); + std::uint64_t k = 0; + const auto paced = [&] { // one vector, waiting for the worker: never late + const auto outputs = h.push({static_cast(k + 1)}, 1); + h.wait_for(++k); + return outputs; + }; + const auto stall = [&] { // the worker stalls 0.2 s; the next vectors arrive meanwhile + REQUIRE(h.p.set_attribute("stall", value{0.2})); + channel_data outputs; + for (int i = 0; i < 5; ++i) { + outputs.push_back(h.push({static_cast(++k)}, 1)[0]); + } + h.wait_for(k); + return outputs; + }; + for (int i = 0; i < 4; ++i) { + paced(); + } + + const auto during = stall(); + THEN("a vector due while it stalled is output as silence") { + CHECK(all_equal(during[2], 0.0)); // due two vectors after the stalled one + } + THEN("once it has caught up, the output is the input two vectors before") { + const auto outputs = paced(); // vector k is in; vector k - 2 is out + CHECK(all_equal(outputs[0], static_cast(k - 2))); + } + THEN("it is reported, from the main thread, once") { + CHECK(h.notified.load() == 1); + h.w.flush_reports(); + CHECK(h.log.contains("late for", log_level::error)); + CHECK(h.lines_containing("late for") == 1); + + AND_WHEN("it stalls again") { + stall(); + h.w.flush_reports(); + THEN("nothing more is reported") { + CHECK(h.notified.load() == 1); + CHECK(h.lines_containing("late for") == 1); + } + } + AND_WHEN("the class is reloaded and it stalls again") { + REQUIRE(h.p.load()); + stall(); + h.w.flush_reports(); + THEN("it is reported again") { + CHECK(h.notified.load() == 2); + CHECK(h.lines_containing("late for") == 2); + } + } + } +} + +SCENARIO("A worker a whole ring behind drops new inputs until it catches up (plan 2.5)") { + ensure_runtime(); + harness h{"stalls"}; + REQUIRE(h.p.load()); + h.w.start(1, 1, k_frames, 2, 0.0); // no sample rate: the least backlog, 16 vectors (18 slots) + h.push({1.0}, 1); + h.push({2.0}, 1); + h.wait_for(2); + + REQUIRE(h.p.set_attribute("stall", value{0.3})); + for (std::uint64_t k = 2; k < 32; ++k) { // the worker is stuck on vector 2 + h.push({static_cast(k + 1)}, 1); + } + h.wait_for(32); + h.w.flush_reports(); + THEN("the vectors beyond the ring were dropped, and it says so") { + CHECK(h.log.contains("input of 12 vector(s) was dropped", log_level::error)); + } + THEN("a dropped vector's output is silence, without counting it late") { + h.w.flush_reports(); // what was late during the stall has been reported + const auto outputs = h.push({33.0}, 1); // vector 30's output is due: dropped + h.wait_for(33); + CHECK(all_equal(outputs[0], 0.0)); + h.w.flush_reports(); + CHECK(h.lines_containing("late for") == 1); + } + THEN("afterwards it runs at the same latency") { + h.push({33.0}, 1); + h.wait_for(33); + h.push({34.0}, 1); + h.wait_for(34); + const auto outputs = h.push({35.0}, 1); // vector 34 in, vector 32 (input 33.0) out + CHECK(all_equal(outputs[0], 33.0)); + } +} + +SCENARIO("A worker can be restarted with new settings, and stopped (plan 2.5)") { + ensure_runtime(); + harness h{"stalls"}; + REQUIRE(h.p.load()); + h.w.start(1, 1, k_frames, 2, 48000.0); + h.push({1.0}, 1); + h.push({2.0}, 1); + + WHEN("it is restarted with another vector size and latency") { + h.w.start(1, 1, 128, 3, 48000.0); + THEN("the latency is the new one, and what was queued is gone") { + CHECK(h.w.latency_samples() == 3 * 128); + for (std::uint64_t k = 0; k < 5; ++k) { + const auto outputs = h.push({static_cast(k + 10)}, 1, 128); + h.wait_for(k + 1); + CHECK(all_equal(outputs[0], k < 3 ? 0.0 : static_cast(k - 3 + 10))); + } + } + } + WHEN("it is stopped") { + h.w.stop(); + THEN("it outputs silence, and nothing is running") { + CHECK_FALSE(h.w.running()); + CHECK(h.w.latency_samples() == 0); + CHECK(all_equal(h.push({5.0}, 1)[0], 0.0)); + } + } + WHEN("it is destroyed while the class stalls") { + REQUIRE(h.p.set_attribute("stall", value{0.2})); + h.push({3.0}, 1); + std::this_thread::sleep_for(std::chrono::milliseconds{50}); // into the stall + THEN("stopping waits for the vector in progress") { + h.w.stop(); // joins: returns once the stall is over + CHECK_FALSE(h.w.running()); + } + } +} + +SCENARIO("A reload while the worker runs takes effect without a pause on the audio thread (plan 2.5)") { + ensure_runtime(); + write_script("worker_reload", + "class worker_reload:\n def process(self, x: float) -> float:\n return x\n"); + harness h{"worker_reload"}; + REQUIRE(h.p.load()); + h.w.start(1, 1, k_frames, 2, 48000.0); + + std::atomic running{true}; + std::atomic pushed{0}; + std::thread audio{[&] { // the audio thread, at about real time (64 frames at 48 kHz) + while (running.load()) { + h.push({1.0}, 1); + ++pushed; + std::this_thread::sleep_for(std::chrono::microseconds{1333}); + } + }}; + for (int i = 0; i < 10; ++i) { + write_script("worker_reload", + "class worker_reload:\n def process(self, x: float) -> float:\n return x * " + + std::to_string(i % 2 == 0 ? 2 : 1) + "\n"); + REQUIRE(h.p.load()); + std::this_thread::sleep_for(std::chrono::milliseconds{20}); + } + running = false; + audio.join(); + + const auto queued = pushed.load(); + h.wait_for(queued); // all it was given while reloading + h.push({1.0}, 1); + h.wait_for(queued + 1); + h.push({1.0}, 1); + h.wait_for(queued + 2); + const auto outputs = h.push({1.0}, 1); // vector `queued` out: the first after the reloads + THEN("the last reload is what plays") { + CHECK(all_equal(outputs[0], 1.0)); // the tenth load: x * 1 + } +} diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index dbc421d..0aa8519 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -150,8 +150,8 @@ while audio ran segfaulted in 5 of 5 runs. - **Underruns.** A slot not done when its outputs are due is output as silence and counted; the worker still processes it when it gets there (so the class's state stays continuous) and discards its outputs, catching up through the backlog, so the latency stays *L*. If it falls - a whole ring behind (the ring holds *L* + a margin), the oldest inputs are dropped, which the - class sees as a gap. Both are reported once per load from the main thread (`flush_reports()`), + a whole ring behind (the ring holds *L* + a margin), new inputs are dropped until it catches + up, which the class sees as a gap. Both are reported once per load from the main thread (`flush_reports()`), never printed on the audio thread. - **`prepare()` and the mode.** The ring is sized when the chain compiles (`dspsetup`: vector size, and the object's inlet and outlet counts), with the worker stopped and restarted around @@ -171,6 +171,20 @@ while audio ran segfaulted in 5 of 5 runs. one Python call per host vector — batching several per call would cut the per-call overhead further (worker mode's other win) at more latency, a later option (`@block`) if measurements show it pays. + - *(a) the core — done:* `core/include/tap/python/worker.h`. The ring is single producer, single + consumer, with a sequence number per slot: the audio thread queues a vector only into a slot + the worker has finished with, so a full ring drops the new vector rather than racing the + worker for an old one; the margin is a quarter of a second, at least 16 vectors. The audio + thread borrows the ring for each vector by taking an atomic pointer, so `start()` and `stop()` + — which a host may call while its old signal chain still runs — wait at most one vector, and + a vector arriving meanwhile is silence. Reports are once per load, by the processor's new + `load_count()`. Core battery: the output is the direct output *L* vectors later (per sample + and per vector, *L* = 1–3, two channels); the host's channels matched to the ring; a stall + goes silent, is reported once, comes back at the same latency, and is reported again after a + reload; a stall past the ring drops exactly the vectors beyond it; restart, stop, and stop + during a stall; ten reloads under an audio thread. Clean under TSan (locally, macOS) — the + Linux CI job runs it too. *(b) the Max object:* `@mode`, `@latency`, `@latencysamples`, the + ring sized in `dspsetup`; runtime test in Max. - [x] **2.6 Shorter reload stalls** — compile outside the swap and hold the GIL only for the swap. *Measured first* (`core/bench/reload_bench.cpp`: an audio thread with Core Audio's real-time scheduling computes 512-sample buffers of 64-sample vectors at 96 kHz while the main thread saves From 712142c1ab484282ae8612a0616b420cc0302f86 Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Wed, 30 Sep 2026 20:51:41 -0500 Subject: [PATCH 12/15] =?UTF-8?q?2.5=20(b):=20worker=20mode=20in=20the=20M?= =?UTF-8?q?ax=20object=20=E2=80=94=20@mode,=20@latency,=20@latencysamples?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit @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) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- CHANGELOG.md | 13 + CLAUDE.md | 6 + ReadMe.md | 5 +- core/include/tap/python/processor.h | 11 +- core/include/tap/python/worker.h | 58 +- core/tests/python/reserved_field.py | 11 + core/tests/test_safety.cpp | 16 + core/tests/test_worker.cpp | 12 + docs/PRODUCTION-PLAN.md | 27 +- docs/tap.python~.maxref.xml | 17 +- runtime-tests/make_patchers.py | 45 +- .../tap.python~.worker.maxtest.maxpat | 3078 +++++++++++++++++ runtime-tests/python/maxtest_stall.py | 13 + runtime-tests/run.py | 3 +- .../tap.python_tilde/tap.python_tilde.h | 178 +- .../tap.python_tilde_test.cpp | 45 + 16 files changed, 3485 insertions(+), 53 deletions(-) create mode 100644 core/tests/python/reserved_field.py create mode 100644 runtime-tests/patchers/tap.python~.worker.maxtest.maxpat create mode 100644 runtime-tests/python/maxtest_stall.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 8274126..8b7bb26 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,19 @@ breaking changes to the contract are allowed where they buy correctness (D5 in ## Unreleased +### Added — worker mode + +- **`@mode worker` runs `process()` on a thread of its own**, `@latency` milliseconds behind the + audio (30 by default, rounded up to whole signal vectors; it must exceed Max's I/O vector), so + that nothing else Python does — a + reload, a message, another instance — can hold up the audio thread, which only copies vectors to + and from it. Vectors the worker is late for are output as silence, reported once per load, and + the delay stays the same; the read-only `@latencysamples` gives it in samples. The worker thread + has the real-time scheduling of an audio thread. `@mode direct`, the default, is as before. + (Plan 2.5.) *Changed with it:* the object's own attributes `mode`, `latency` and + `latencysamples` are reserved — a class's field or method of one of those names is not exposed, + and the console says so (before, fields were never checked against reserved names). + ### Added — several inputs and outputs - **process() can take several signal inputs and return several outputs.** Its parameters are the diff --git a/CLAUDE.md b/CLAUDE.md index dd254cf..60cebde 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -108,6 +108,12 @@ the secrets exist, and attaches zips + SHA256s to a draft release. (and copies) of what it uses before running anything that could yield. Keep it that way. - `gil_lock` gives each thread one long-lived Python thread state (`detail::thread_state_keeper`); don't call `PyGILState_Ensure` directly. +- **Worker mode** (`@mode worker`, plan 2.5): `process()` runs on the worker's own thread instead, + and the audio thread only copies vectors through `worker`'s lock-free ring — no GIL, no + allocation, no Python. The worker thread must have audio-thread scheduling (the wrapper's + `audio_thread_scheduling`, through the core's `thread_setup` hook): an ordinary thread was late + even at 21 ms of latency on a busy machine. `worker::start()`/`stop()` join threads, so never call + them holding the GIL. - **Nothing prints on the audio thread.** Problems in `process()` are recorded (exception object, flags) and the host's `report_ready` callback fires — the external sets a `queue<>` — and `flush_reports()` prints them on the main thread. Anything new on the audio path follows suit. diff --git a/ReadMe.md b/ReadMe.md index 5e8ea59..0b5fe84 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -87,19 +87,20 @@ Without a runtime the object still loads, and says in the Max console what is mi Python sources live in the package's `python` folder. `[tap.python~ name]` loads `python/name.py` and instantiates the class `name` defined in it (the file, class, and argument must share the same name, which must be a valid Python identifier; with no argument, `default` is loaded). The file is loaded by its path, never through `import`, so a file named like a standard-library module (`random.py`, `json.py`) works and does not shadow that module for anyone else. Other files in the `python` folder can be imported by your class as helper modules (the folder is on `sys.path`, after the standard library). Text is UTF-8: the interpreter runs in Python's UTF-8 mode, so `open()` reads and writes UTF-8 unless you pass another `encoding`, whatever the machine's locale. - **Attributes** — class-level annotated fields (e.g. via `attrs`) become Max attributes. `int` maps to a Max `long`, `float` to `float64`, `bool` to an on/off `long` (your field receives a real `bool`), anything else to a symbol; `Optional[X]` and `X | None` count as `X`. Names starting with `_` are private, and `ClassVar`s are not fields. If a hint cannot be resolved (say a name imported only under `TYPE_CHECKING`), the console says so and the annotation is read as written. -- **Messages** — public methods (including classmethods and staticmethods) become Max messages, called according to their signature: parameters with defaults are optional, `*args` takes any number of arguments, and a keyword-only parameter must have a default (a method with a required keyword-only parameter is not exposed). Argument hints (`int`, `float`, `bool`, `str`) drive the conversion from Max atoms; an unannotated parameter receives the atom as it is (an `int`, `float` or `str`). Methods named `int`, `float`, `symbol`, and `bang` map to those standard Max messages. Names Max or the object handle themselves (`filechanged`, `dsp64`, `notify`, `assist`, `loadbang`, `dblclick`, `anything`, …) are not exposed; the console names any method skipped this way so you can rename it. +- **Messages** — public methods (including classmethods and staticmethods) become Max messages, called according to their signature: parameters with defaults are optional, `*args` takes any number of arguments, and a keyword-only parameter must have a default (a method with a required keyword-only parameter is not exposed). Argument hints (`int`, `float`, `bool`, `str`) drive the conversion from Max atoms; an unannotated parameter receives the atom as it is (an `int`, `float` or `str`). Methods named `int`, `float`, `symbol`, and `bang` map to those standard Max messages. Names Max or the object handle themselves (`filechanged`, `dsp64`, `notify`, `assist`, `loadbang`, `dblclick`, `anything`, …, and the object's own attributes `mode`, `latency` and `latencysamples`) are not exposed — as methods, or as fields; the console names any skipped this way so you can rename it. - **Audio** — a method `process()` runs on the signal, in one of two forms chosen by its type hint: - `process(self, x: np.ndarray) -> np.ndarray` is called **once per signal vector** with a numpy array of the input and must return an array of the same length (any numeric dtype, or a list; it is converted). This is the form to use for anything that must run in real time — see `python/numpy_gain.py`, and `python/numpy_allpass.py` for a filter with feedback. The input array is reused from one call to the next: copy it if you want to keep it. - `process(self, x: float) -> float` is called **once per sample** — simplest for sketching; the call is cheap, but every line of Python in it runs once per sample (see [the performance note](#a-note-on-performance)). Its parameters are the object's signal inlets and its return hint its outlets: `process(self, left: np.ndarray, right: np.ndarray) -> tuple[np.ndarray, np.ndarray]` makes an object with two of each (see `python/stereo_width.py`), and `process(self) -> float`, with no inputs, a generator — the first inlet is always there, for messages. The inputs are all `np.ndarray` or all per sample, and a tuple return must say how many values it has (`tuple[float, float]`). A save that changes how many changes the object's inlets and outlets to match, keeping the patch cords of those that stay. Wrap the object in `mc.` to run one instance per channel of a multichannel signal. Output that is not a number, or not finite (NaN, infinity), is replaced with 0.0 and reported once in the Max console, as is a return with the wrong number of values. +- **Worker mode** — by default `process()` runs on Max's audio thread, so whatever else holds Python's interpreter — a reload, a message, another instance — holds up the audio while it does. With `@mode worker` it runs on a thread of its own instead, `@latency` milliseconds behind the audio (30 by default, rounded up to whole signal vectors): the audio thread then only copies vectors to and from that thread, and never waits for Python. Max computes a whole I/O vector's worth of signal vectors at once, so `@latency` must be longer than the I/O vector (Options > Audio Status: 512 samples is 11.6 ms at 44.1 kHz) — what is left over is the time Python has to keep up; raise it with a larger I/O vector. If Python falls further behind, the vectors it is late for are output as silence and the console says so, once per load; the delay stays the same. The read-only `@latencysamples` gives the delay in samples, for aligning other signal paths (a `delay~`, say); in direct mode it is 0. The worker thread has the real-time scheduling of an audio thread. `@mode` and `@latency` take effect as soon as they are set, by rebuilding the signal chain. - **Audio settings** — an optional method `prepare(self, sample_rate: float, vector_size: int) -> None` is called with Max's sample rate and vector size before the object processes any audio, again whenever they change, and on every reload before the new code runs. `python/allpass.py` uses it to size its delay line. - **Hot reload** — saving the `.py` file reloads it in place, as a fresh module (names you deleted from the file are gone): the attributes and messages follow the new class, and audio resumes with the new code. Until the new code is ready the object keeps running the old one, so a successful reload swaps in without a gap in the audio. Attribute values carry over — set from the patcher or by your own code — for every attribute the new class still has with the same type; an attribute whose type changed starts from its new default, and one you removed disappears from the object. If the file has an error, the object prints the traceback to the Max console and outputs silence until the next successful reload (and the attribute values come back with it); a save that breaks a file shared by many objects is reported once, not by each, while an object created later with the file still broken says so again. Every object using the same file shares one execution of it per save, and the console says so once — `Loaded name.py: process() bound, one call per sample` (or per vector), from whichever object ran the file — along with anything true of the class, such as a method skipped for its name; a save that changes nothing reloads silently. Errors that belong to one object, such as an exception in its constructor, are still reported by each. Max's file watcher notices a save within a couple of seconds, but it coalesces saves made in quick succession — a script saving once a second, say — so the object then reloads for only some of them, and can lag behind until they stop; sending the object `filechanged` reloads it at once. - **Errors** — an exception raised by your code (in `process()`, a message, an attribute setter, the constructor or at import) prints its traceback to the Max console; it never takes Max down. That includes `sys.exit()`, which is reported like any other exception rather than quitting Max. ### A note on performance -`process()` runs on the audio thread, holding Python's global interpreter lock. The per-sample form (`x: float`) makes one Python call per sample. The call itself is cheap — a fraction of a percent of a core, in the measurements below — but every line of Python in it runs 48,000 or 96,000 times a second, so the cost is your code's: `allpass.py`, a few lines of indexing and arithmetic, costs more than twenty times the call — and `numpy_allpass.py`, the same filter written a vector at a time, a small fraction of it. It is fantastic for sketching and live-coding an algorithm. The numpy form (`x: np.ndarray`) makes one call per signal vector, and numpy then works on the whole vector at C speed: it is the one to use when the algorithm has real work in it and has to keep up. Either way the audio thread waits while other Python code holds the interpreter — a reload, a message, or another instance: all `tap.python~` instances share one interpreter, so heavy Python work in one can steal time from the others. The object has Python hand the interpreter to a waiting thread after half a millisecond — a tenth of CPython's default — so a reload, which holds it for a few milliseconds, delays the audio a little at a time instead of all at once: measured with `core/bench`'s reload benchmark (96 kHz, 512-sample buffers, a save every 100 ms), no buffer was late at 0.5 ms, where CPython's default left some late in most runs. Errors in `process()` are printed from Max's main thread, never from the audio thread. +`process()` runs on the audio thread, holding Python's global interpreter lock. The per-sample form (`x: float`) makes one Python call per sample. The call itself is cheap — a fraction of a percent of a core, in the measurements below — but every line of Python in it runs 48,000 or 96,000 times a second, so the cost is your code's: `allpass.py`, a few lines of indexing and arithmetic, costs more than twenty times the call — and `numpy_allpass.py`, the same filter written a vector at a time, a small fraction of it. It is fantastic for sketching and live-coding an algorithm. The numpy form (`x: np.ndarray`) makes one call per signal vector, and numpy then works on the whole vector at C speed: it is the one to use when the algorithm has real work in it and has to keep up. Either way, in the default direct mode, the audio thread waits while other Python code holds the interpreter — a reload, a message, or another instance: all `tap.python~` instances share one interpreter, so heavy Python work in one can steal time from the others. [Worker mode](#writing-a-class) (`@mode worker`) takes Python off the audio thread, at the cost of a fixed delay. The object has Python hand the interpreter to a waiting thread after half a millisecond — a tenth of CPython's default — so a reload, which holds it for a few milliseconds, delays the audio a little at a time instead of all at once: measured with `core/bench`'s reload benchmark (96 kHz, 512-sample buffers, a save every 100 ms), no buffer was late at 0.5 ms, where CPython's default left some late in most runs. Errors in `process()` are printed from Max's main thread, never from the audio thread. What `process()` costs, measured by `core/bench` — which calls it exactly as Max's audio thread does, one vector at a time — as the share of one CPU core it needs: diff --git a/core/include/tap/python/processor.h b/core/include/tap/python/processor.h index 29fdfa2..b06efac 100644 --- a/core/include/tap/python/processor.h +++ b/core/include/tap/python/processor.h @@ -76,8 +76,9 @@ namespace tap::python { /// @param source_name the module and class name (`.py` defining `class `) /// @param log receives the processor's own diagnostics (may be called on the /// audio thread) - /// @param reserved_messages method names the host handles itself; a Python method with one - /// of these names is not exposed as a message (with a diagnostic) + /// @param reserved_messages names the host handles itself, as messages or attributes; a Python + /// method or annotated field with one of these names is not exposed + /// (with a diagnostic) /// @param report_ready called on the audio thread when something needs reporting; the /// host must then call flush_reports() from its main thread. Must be /// real-time safe (no locks, no allocation). @@ -1166,6 +1167,12 @@ namespace tap::python { if (name.empty() || name[0] == '_' || kind == "ClassVar") { continue; } + if (is_reserved(name)) { // a host attribute or message has the name (plan 2.5) + announce(log_level::error, + "the field " + name + + " is reserved by the host and is not exposed as an attribute; rename the field"); + continue; + } b.attributes.push_back({name, value_type_from_hint(kind)}); } Py_DECREF(result); diff --git a/core/include/tap/python/worker.h b/core/include/tap/python/worker.h index 64cbdfa..dc562ca 100644 --- a/core/include/tap/python/worker.h +++ b/core/include/tap/python/worker.h @@ -48,18 +48,39 @@ namespace tap::python { class worker { public: - /// The latency, in vectors, unless the host says otherwise. - static constexpr std::size_t k_default_latency = 2; + /// The latency, in milliseconds, unless the host says otherwise (plan 2.5). A host that computes + /// several vectors at a time (Max: one I/O vector's worth, back to back) leaves the worker only + /// the latency beyond that burst to do them in, so this covers a 512-sample I/O vector at + /// 44.1 kHz (11.6 ms) with room to spare: measured in Max, 4.7 ms of room was not enough. + static constexpr double k_default_latency_ms = 30.0; + + /// A latency in milliseconds as whole vectors of `vector_size` at `sample_rate`: rounded up, + /// and at least one. + static std::size_t latency_vectors(const double milliseconds, const double sample_rate, + const std::size_t vector_size) { + if (!(milliseconds > 0.0) || !(sample_rate > 0.0) || vector_size == 0 || !std::isfinite(milliseconds) + || !std::isfinite(sample_rate)) { + return 1; + } + const double vectors = milliseconds / 1000.0 * sample_rate / static_cast(vector_size); + return std::max(1, static_cast(std::ceil(vectors - 1e-9))); + } /// @param target the processor to run; it must outlive the worker /// @param log receives the worker's reports (main thread) /// @param report_ready called on the audio thread when something needs reporting; the host /// must then call flush_reports() from its main thread. Must be /// real-time safe, as the processor's is (it may be the same callback). - explicit worker(processor& target, log_function log = {}, std::function report_ready = {}) + /// @param thread_setup called on each worker thread as it starts, with the vector period in + /// seconds (0 if the sample rate is unknown): where the host gives the + /// thread the scheduling an audio thread has. Without it, a busy machine + /// can hold an ordinary thread off for longer than the latency. + explicit worker(processor& target, log_function log = {}, std::function report_ready = {}, + std::function thread_setup = {}) : m_target{target} , m_log{std::move(log)} - , m_report_ready{std::move(report_ready)} {} + , m_report_ready{std::move(report_ready)} + , m_thread_setup{std::move(thread_setup)} {} ~worker() { stop(); } @@ -69,7 +90,9 @@ namespace tap::python { /// Start the worker, or restart it with new settings: a ring for `inputs` and `outputs` host /// channels of `vector_size` frames, `latency` vectors deep (at least 1), with room for the /// worker to fall a quarter of a second behind at `sample_rate` (at least 16 vectors). - /// Whatever the previous worker had not processed is discarded. Main thread. + /// Whatever the previous worker had not processed is discarded. Returns once the new thread + /// is running with its Python thread state, which it takes the GIL to make: main thread, + /// never holding the GIL. void start(const std::size_t inputs, const std::size_t outputs, const std::size_t vector_size, const std::size_t latency, const double sample_rate) { stop(); @@ -81,8 +104,21 @@ namespace tap::python { : std::size_t{0}; auto next = std::make_unique(inputs, outputs, frames, vectors, vectors + std::max(k_min_backlog, backlog)); - ring* r = next.get(); - r->thread = std::thread{[this, r] { run(*r); }}; + ring* r = next.get(); + const auto period = + std::isfinite(sample_rate) && sample_rate > 0.0 ? static_cast(frames) / sample_rate : 0.0; + r->thread = std::thread{[this, r, period] { + if (m_thread_setup) { + m_thread_setup(period); + } + if (Py_IsInitialized()) { + gil_lock lock; // the thread's Python thread state, made now rather than on its first vector + } + r->ready.store(true, std::memory_order_release); + r->ready.notify_one(); + run(*r); + }}; + r->ready.wait(false, std::memory_order_acquire); // ready before the audio thread can give it work m_owned = std::move(next); m_latency = vectors * frames; m_ring.store(r, std::memory_order_release); @@ -240,12 +276,14 @@ namespace tap::python { std::atomic done{}; // vectors the worker has finished (or passed over) std::atomic signal{}; // bumped to wake the worker std::atomic stopping{}; + std::atomic ready{}; // the thread has started and has its Python thread state std::thread thread; }; - processor& m_target; - log_function m_log; - std::function m_report_ready; + processor& m_target; + log_function m_log; + std::function m_report_ready; + std::function m_thread_setup; std::atomic m_ring{}; // the running ring, while the audio thread is not using it std::unique_ptr m_owned; // the running ring (main thread) diff --git a/core/tests/python/reserved_field.py b/core/tests/python/reserved_field.py new file mode 100644 index 0000000..739b7cd --- /dev/null +++ b/core/tests/python/reserved_field.py @@ -0,0 +1,11 @@ +# Test fixture: annotated fields named like attributes the host reserves (plan 2.5: worker mode's +# mode and latency). + + +class reserved_field: + mode: str = "fast" + latency: int = 3 + level: float = 1.0 + + def process(self, x: float) -> float: + return x * self.level diff --git a/core/tests/test_safety.cpp b/core/tests/test_safety.cpp index bb4ed09..67ab0cb 100644 --- a/core/tests/test_safety.cpp +++ b/core/tests/test_safety.cpp @@ -152,6 +152,22 @@ SCENARIO("Methods named like reserved host messages are not exposed") { CHECK(p.has_process()); } +SCENARIO("Fields named like reserved host attributes are not exposed (plan 2.5)") { + ensure_runtime(); + log_capture log; + processor p{"reserved_field", log.sink(), {"mode", "latency"}}; + REQUIRE(p.load()); + + std::vector names; + for (const auto& a : p.attributes()) { + names.push_back(a.name); + } + CHECK(names == std::vector{"level"}); + CHECK(log.contains("the field mode is reserved", log_level::error)); + CHECK(log.contains("the field latency is reserved", log_level::error)); + CHECK(p.has_process()); +} + // 1.4 — the audio thread keeps one Python thread state for its lifetime, rather than creating // and destroying one (with its allocations and interpreter-wide lock) every vector. diff --git a/core/tests/test_worker.cpp b/core/tests/test_worker.cpp index b34e825..9fe1a8a 100644 --- a/core/tests/test_worker.cpp +++ b/core/tests/test_worker.cpp @@ -9,6 +9,7 @@ #include #include #include +#include #include #include #include @@ -124,6 +125,17 @@ SCENARIO("In worker mode the output is the direct output, the latency later (pla CHECK(h.notified.load() == 0); } +SCENARIO("A latency in milliseconds is whole vectors, rounded up, at least one (plan 2.5)") { + CHECK(worker::latency_vectors(10.0, 96000.0, 64) == 15); + CHECK(worker::latency_vectors(10.0, 44100.0, 64) == 7); // 6.9 + CHECK(worker::latency_vectors(10.0, 48000.0, 512) == 1); // 0.94 + CHECK(worker::latency_vectors(4.0, 48000.0, 64) == 3); // exactly 3, despite rounding error + CHECK(worker::latency_vectors(0.0, 48000.0, 64) == 1); + CHECK(worker::latency_vectors(-5.0, 48000.0, 64) == 1); + CHECK(worker::latency_vectors(10.0, 0.0, 64) == 1); + CHECK(worker::latency_vectors(std::numeric_limits::quiet_NaN(), 48000.0, 64) == 1); +} + SCENARIO("The host's channels are matched to the worker's ring (plan 2.5)") { ensure_runtime(); harness h{"two_by_two"}; diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index 0aa8519..3eededb 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -143,10 +143,11 @@ while audio ran segfaulted in 5 of 5 runs. matching — so the class contract does not change. Slot states are atomics (single producer, single consumer, no locks); the audio thread wakes the worker with a C++20 atomic notify, which never blocks. The worker's thread is created and joined on the main thread. - - **Latency** *L* is whole vectors, set by `@latency` (in vectors, default 2), and reported in - samples (*L* × vector size) by the read-only `@latencysamples`, which a patch can read to align - other paths. Max has no documented call for an MSP object to report latency to the host, so - none is used; the output is primed with *L* vectors of silence. + - **Latency** *L* is whole vectors, set by `@latency` in milliseconds (default 30, rounded up to + whole vectors, at least one — *revised twice after measuring, below: from "vectors, default 2", + then from 10 ms*), and reported in samples (*L* × vector size) by the read-only `@latencysamples`, which + a patch can read to align other paths. Max has no documented call for an MSP object to report + latency to the host, so none is used; the output is primed with *L* vectors of silence. - **Underruns.** A slot not done when its outputs are due is output as silence and counted; the worker still processes it when it gets there (so the class's state stays continuous) and discards its outputs, catching up through the backlog, so the latency stays *L*. If it falls @@ -184,7 +185,23 @@ while audio ran segfaulted in 5 of 5 runs. reload; a stall past the ring drops exactly the vectors beyond it; restart, stop, and stop during a stall; ten reloads under an audio thread. Clean under TSan (locally, macOS) — the Linux CI job runs it too. *(b) the Max object:* `@mode`, `@latency`, `@latencysamples`, the - ring sized in `dspsetup`; runtime test in Max. + ring sized in `dspsetup`; runtime test in Max. *Found in Max:* an ordinary worker thread was + late for vectors in 2 of 5 quiet seconds even with 32 vectors (21 ms) of latency, on a busy + machine (load average 6–11); the worker now gets the real-time scheduling of an audio thread — + a hook the core calls on the thread as it starts (`thread_setup`), where the wrapper sets + Mach's time-constraint policy (macOS: a period of one vector, half of it computation) or + `THREAD_PRIORITY_TIME_CRITICAL` (Windows). With it, at 96 kHz and 64-sample vectors, the seconds + with a late vector: 10 of 10 at 2 vectors (1.3 ms), 10 of 10 at 4, 3 of 10 at 8 (5.3 ms), none + at 16 (10.7 ms) — and a reload's hold on the GIL (2.6: about 3.5 ms) is longer than 2 vectors + there. Hence a latency in milliseconds, which stays the same delay whatever the vector size. + *Then:* Max computes a whole I/O vector of signal vectors back to back (here 512 samples, so 8 + at a time), and the worker has only the latency beyond that burst to do them in — which is why + 8 vectors (512 samples) failed and 16 did not. 10 ms (960 samples here, 4.7 ms beyond the + burst) still left late vectors in 2 of 11 seconds, and at 44.1 or 48 kHz with Max's usual + 512-sample I/O vector it would leave nothing. Decided: `@latency` stays the whole delay, + default 30 ms, documented as having to exceed the I/O vector's duration (measuring the burst + and adding to it was the alternative). Fields as well as methods are now checked against the host's reserved names + (`mode`, `latency` and `latencysamples` among them). - [x] **2.6 Shorter reload stalls** — compile outside the swap and hold the GIL only for the swap. *Measured first* (`core/bench/reload_bench.cpp`: an audio thread with Core Audio's real-time scheduling computes 512-sample buffers of 64-sample vectors at 96 kHz while the main thread saves diff --git a/docs/tap.python~.maxref.xml b/docs/tap.python~.maxref.xml index 6cc5050..0be3718 100644 --- a/docs/tap.python~.maxref.xml +++ b/docs/tap.python~.maxref.xml @@ -7,7 +7,7 @@ Process audio with a Python class - Process audio with a Python class. The argument names a file in the package's python folder, which must define a class of the same name. The class's type-annotated public fields become attributes (int, float, bool and str; Optional allowed), and its public methods become messages called according to their signatures, with methods named int, float, symbol and bang answering those standard messages. Its process() method runs on the signal: once per signal vector when annotated with numpy arrays, or once per sample when annotated with float; its parameters are the object's signal inlets, and its return hint its outlets (a tuple of values for more than one). An optional prepare(sample_rate, vector_size) method receives the audio settings before audio starts and whenever they change. The file is watched and reloaded when saved, keeping attribute values; a save that changes process()'s inputs or outputs changes the inlets and outlets to match, keeping the patch cords of those that stay. Errors are printed to the Max console and never take Max down. + Process audio with a Python class. The argument names a file in the package's python folder, which must define a class of the same name. The class's type-annotated public fields become attributes (int, float, bool and str; Optional allowed), and its public methods become messages called according to their signatures, with methods named int, float, symbol and bang answering those standard messages. Its process() method runs on the signal: once per signal vector when annotated with numpy arrays, or once per sample when annotated with float; its parameters are the object's signal inlets, and its return hint its outlets (a tuple of values for more than one). An optional prepare(sample_rate, vector_size) method receives the audio settings before audio starts and whenever they change. With mode worker, process() runs on a thread of its own, latency milliseconds behind the audio, so that nothing else Python does can hold the audio up. The file is watched and reloaded when saved, keeping attribute values; a save that changes process()'s inputs or outputs changes the inlets and outlets to match, keeping the patch cords of those that stay. Errors are printed to the Max console and never take Max down. @@ -46,6 +46,21 @@ + + The latency in worker mode, in milliseconds (0 to 1000), rounded up to whole signal vectors, at least one + The latency in worker mode, in milliseconds (0 to 1000), rounded up to whole signal vectors, at least one. It must be longer than Max's I/O vector, which Max computes all at once: what is left over is the time Python has to keep up. More absorbs longer pauses, at the cost of delay. + + + + The delay worker mode adds, in samples (latency rounded up to whole signal vectors), for aligning other signal paths; 0 in direct mode or with audio off + The delay worker mode adds, in samples (latency rounded up to whole signal vectors), for aligning other signal paths; 0 in direct mode or with audio off. + + + + Where process() runs: direct, on the audio thread, with no latency; or worker, on a thread of its own, about latency milliseconds behind, so that nothing Python does elsewhere (a reload, a message, a garbage collection) can hold up the audio + Where process() runs: direct, on the audio thread, with no latency; or worker, on a thread of its own, about latency milliseconds behind, so that nothing Python does elsewhere (a reload, a message, a garbage collection) can hold up the audio. + + diff --git a/runtime-tests/make_patchers.py b/runtime-tests/make_patchers.py index f339679..b0882bd 100644 --- a/runtime-tests/make_patchers.py +++ b/runtime-tests/make_patchers.py @@ -608,6 +608,49 @@ def outlet(box: str, n: int) -> str: # a box passing outlet n of `box` on, to s return t +def worker(latency_ms: float | None = None, quiet_windows: int = 0) -> Test: + t = Test("tap.python~.worker.maxtest.maxpat", + "Worker mode (plan 2.5), at its default latency: with @mode worker the output is the input " + "delayed by @latencysamples, sample for sample what delay~ gives, and stays so through a " + "reload; a class that stalls for 0.2 s is late, reported once, and comes back at the same " + "latency; @mode direct takes the delay away.") + ramp = t.obj("phasor~ 50", signal=True) # a new value every sample, so any delay shows + py = t.python("maxtest_stall @mode worker" + (f" @latency {latency_ms}" if latency_ms is not None else "")) + delay = t.obj("delay~ 48000 0", inlets=2, signal=True) + late = t.obj("-~", inlets=2, signal=True) # the object's output less the input, delayed + now = t.obj("-~", inlets=2, signal=True) # the object's output less the input + for source, destination in ((ramp, py), (ramp, delay), (py, late), (py, now)): + t.patcher.connect(source, 0, destination) + t.patcher.connect(delay, 0, late, 1) + t.patcher.connect(ramp, 0, now, 1) + delay_by_latency = t.patcher.box("getattr latencysamples @listen 0", outlets=3, column=3) + t.patcher.connect(delay_by_latency, 1, py) + t.patcher.connect(delay_by_latency, 0, delay, 1) + t.count_errors("late.for") + + watch = t.no_change("delayed-by-latencysamples", late, 0.0) + after = t.no_change("same-latency-after-stall", late, 0.0) + windows = [t.no_change(f"quiet-window-{i}", late, 0.0) for i in range(quiet_windows)] + # each step waits, then acts (so a watch starts a step after what it depends on) + t.step(t.attribute_compare("latency-reported-in-samples", py, "latencysamples", "> 0"), delay_by_latency, + t.log_attribute("latencysamples", py, "latencysamples")) + t.step(watch[0]) + t.step(watch[1], wait=1000) + for start, check in windows: # (for measuring: none in the committed test) + t.step(start) + t.step(check, wait=1000) + t.step(t.send("stall 0.2", py)) + t.step(t.errors_are("stall-reported-once", "== 1", "late.for"), after[0], wait=1000) + t.step(after[1], wait=1000) + t.step(t.send("filechanged", py)) + t.step(t.sample_equals("delayed-after-reload", late, 0.0), wait=500) + t.step(t.send("mode direct", py)) + t.step(t.attribute_equals("direct-reports-no-latency", py, "latencysamples", 0), + t.sample_equals("direct-has-no-delay", now, 0.0), + t.errors_are("console-only-the-stall", "== 1"), wait=500) + return t + + def announce_once() -> Test: t = Test("tap.python~.announce-once.maxtest.maxpat", "What is true of a class is said once per run of its file, however many objects share it " @@ -821,7 +864,7 @@ def without_runtime_restart() -> Test: TESTS_TO_WRITE = [load, attributes_and_messages, reload, reload_under_audio, many_instances, channels, announce_once, faults, - prepare, + prepare, worker, without_runtime, without_runtime_restart] diff --git a/runtime-tests/patchers/tap.python~.worker.maxtest.maxpat b/runtime-tests/patchers/tap.python~.worker.maxtest.maxpat new file mode 100644 index 0000000..7a8ce54 --- /dev/null +++ b/runtime-tests/patchers/tap.python~.worker.maxtest.maxpat @@ -0,0 +1,3078 @@ +{ + "patcher": { + "fileversion": 1, + "appversion": { + "major": 9, + "minor": 0, + "revision": 8, + "architecture": "x64", + "modernui": 1 + }, + "classnamespace": "box", + "rect": [ + 60.0, + 80.0, + 1290, + 900.0 + ], + "default_fontsize": 12.0, + "default_fontname": "Arial", + "gridsize": [ + 15.0, + 15.0 + ], + "description": "tap.python~.worker", + "boxes": [ + { + "box": { + "id": "obj-1", + "maxclass": "comment", + "numinlets": 1, + "numoutlets": 0, + "patching_rect": [ + 20.0, + 20.0, + 480, + 80.0 + ], + "text": "tap.python~.worker\n\nWorker mode (plan 2.5), at its default latency: with @mode worker the output is the input delayed by @latencysamples, sample for sample what delay~ gives, and stays so through a reload; a class that stalls for 0.2 s is late, reported once, and comes back at the same latency; @mode direct takes the delay away.", + "linecount": 4 + } + }, + { + "box": { + "id": "obj-2", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 520.0, + 20.0, + 86.0, + 22.0 + ], + "text": "phasor~ 50" + } + }, + { + "box": { + "id": "obj-3", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 520.0, + 50.0, + 282.0, + 22.0 + ], + "text": "tap.python~ maxtest_stall @mode worker" + } + }, + { + "box": { + "id": "obj-4", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 520.0, + 80.0, + 114.0, + 22.0 + ], + "text": "delay~ 48000 0" + } + }, + { + "box": { + "id": "obj-5", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 520.0, + 110.0, + 40.0, + 22.0 + ], + "text": "-~" + } + }, + { + "box": { + "id": "obj-6", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 520.0, + 140.0, + 40.0, + 22.0 + ], + "text": "-~" + } + }, + { + "box": { + "id": "obj-7", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 3, + "outlettype": [ + "", + "", + "" + ], + "patching_rect": [ + 770.0, + 20.0, + 240.0, + 22.0 + ], + "text": "getattr latencysamples @listen 0" + } + }, + { + "box": { + "id": "obj-8", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 20.0, + 65.0, + 22.0 + ], + "text": "error 1" + } + }, + { + "box": { + "id": "obj-9", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 5, + "outlettype": [ + "", + "", + "", + "", + "" + ], + "patching_rect": [ + 1020.0, + 50.0, + 121.0, + 22.0 + ], + "text": "regexp late.for" + } + }, + { + "box": { + "id": "obj-10", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 80.0, + 40.0, + 22.0 + ], + "text": "t b" + } + }, + { + "box": { + "id": "obj-11", + "maxclass": "newobj", + "numinlets": 3, + "numoutlets": 4, + "outlettype": [ + "", + "", + "", + "" + ], + "patching_rect": [ + 1020.0, + 110.0, + 135.0, + 22.0 + ], + "text": "counter 1 1000000" + } + }, + { + "box": { + "id": "obj-12", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 770.0, + 50.0, + 65.0, + 22.0 + ], + "text": "!=~ 0.0" + } + }, + { + "box": { + "id": "obj-13", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 80.0, + 72.0, + 22.0 + ], + "text": "peakamp~" + } + }, + { + "box": { + "id": "obj-14", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 770.0, + 110.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-15", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 140.0, + 40.0, + 22.0 + ], + "text": "t b" + } + }, + { + "box": { + "id": "obj-16", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 170.0, + 44.0, + 22.0 + ], + "text": "gate" + } + }, + { + "box": { + "id": "obj-17", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 200.0, + 40.0, + 22.0 + ], + "text": "1" + } + }, + { + "box": { + "id": "obj-18", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 230.0, + 44.0, + 22.0 + ], + "text": "== 0" + } + }, + { + "box": { + "id": "obj-19", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 260.0, + 275.0, + 22.0 + ], + "text": "test.assert delayed-by-latencysamples" + } + }, + { + "box": { + "id": "obj-20", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "signal" + ], + "patching_rect": [ + 770.0, + 290.0, + 65.0, + 22.0 + ], + "text": "!=~ 0.0" + } + }, + { + "box": { + "id": "obj-21", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 320.0, + 72.0, + 22.0 + ], + "text": "peakamp~" + } + }, + { + "box": { + "id": "obj-22", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 770.0, + 350.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-23", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 380.0, + 40.0, + 22.0 + ], + "text": "t b" + } + }, + { + "box": { + "id": "obj-24", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 410.0, + 44.0, + 22.0 + ], + "text": "gate" + } + }, + { + "box": { + "id": "obj-25", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 440.0, + 40.0, + 22.0 + ], + "text": "1" + } + }, + { + "box": { + "id": "obj-26", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 470.0, + 44.0, + 22.0 + ], + "text": "== 0" + } + }, + { + "box": { + "id": "obj-27", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 500.0, + 268.0, + 22.0 + ], + "text": "test.assert same-latency-after-stall" + } + }, + { + "box": { + "id": "obj-28", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 3, + "outlettype": [ + "", + "", + "" + ], + "patching_rect": [ + 770.0, + 530.0, + 240.0, + 22.0 + ], + "text": "getattr latencysamples @listen 0" + } + }, + { + "box": { + "id": "obj-29", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 560.0, + 40.0, + 22.0 + ], + "text": "> 0" + } + }, + { + "box": { + "id": "obj-30", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 590.0, + 289.0, + 22.0 + ], + "text": "test.assert latency-reported-in-samples" + } + }, + { + "box": { + "id": "obj-31", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 3, + "outlettype": [ + "", + "", + "" + ], + "patching_rect": [ + 1020.0, + 140.0, + 240.0, + 22.0 + ], + "text": "getattr latencysamples @listen 0" + } + }, + { + "box": { + "id": "obj-32", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 170.0, + 170.0, + 22.0 + ], + "text": "prepend latencysamples" + } + }, + { + "box": { + "id": "obj-33", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 0, + "outlettype": [], + "patching_rect": [ + 1020.0, + 200.0, + 128.0, + 22.0 + ], + "text": "test.log measure" + } + }, + { + "box": { + "id": "obj-34", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 270.0, + 20.0, + 79.0, + 22.0 + ], + "text": "stall 0.2" + } + }, + { + "box": { + "id": "obj-35", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 230.0, + 40.0, + 22.0 + ], + "text": "i" + } + }, + { + "box": { + "id": "obj-36", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 260.0, + 44.0, + 22.0 + ], + "text": "== 1" + } + }, + { + "box": { + "id": "obj-37", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 620.0, + 233.0, + 22.0 + ], + "text": "test.assert stall-reported-once" + } + }, + { + "box": { + "id": "obj-38", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 270.0, + 50.0, + 93.0, + 22.0 + ], + "text": "filechanged" + } + }, + { + "box": { + "id": "obj-39", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 650.0, + 177.0, + 22.0 + ], + "text": "test.sample~ @autorun 0" + } + }, + { + "box": { + "id": "obj-40", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 680.0, + 121.0, + 22.0 + ], + "text": "test.equals 0.0" + } + }, + { + "box": { + "id": "obj-41", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 710.0, + 240.0, + 22.0 + ], + "text": "test.assert delayed-after-reload" + } + }, + { + "box": { + "id": "obj-42", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 270.0, + 80.0, + 93.0, + 22.0 + ], + "text": "mode direct" + } + }, + { + "box": { + "id": "obj-43", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 3, + "outlettype": [ + "", + "", + "" + ], + "patching_rect": [ + 770.0, + 740.0, + 240.0, + 22.0 + ], + "text": "getattr latencysamples @listen 0" + } + }, + { + "box": { + "id": "obj-44", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 770.0, + 44.0, + 22.0 + ], + "text": "== 0" + } + }, + { + "box": { + "id": "obj-45", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 800.0, + 275.0, + 22.0 + ], + "text": "test.assert direct-reports-no-latency" + } + }, + { + "box": { + "id": "obj-46", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 830.0, + 177.0, + 22.0 + ], + "text": "test.sample~ @autorun 0" + } + }, + { + "box": { + "id": "obj-47", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 860.0, + 121.0, + 22.0 + ], + "text": "test.equals 0.0" + } + }, + { + "box": { + "id": "obj-48", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 890.0, + 233.0, + 22.0 + ], + "text": "test.assert direct-has-no-delay" + } + }, + { + "box": { + "id": "obj-49", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 290.0, + 40.0, + 22.0 + ], + "text": "t b" + } + }, + { + "box": { + "id": "obj-50", + "maxclass": "newobj", + "numinlets": 3, + "numoutlets": 4, + "outlettype": [ + "", + "", + "", + "" + ], + "patching_rect": [ + 1020.0, + 320.0, + 135.0, + 22.0 + ], + "text": "counter 1 1000000" + } + }, + { + "box": { + "id": "obj-51", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 350.0, + 40.0, + 22.0 + ], + "text": "i" + } + }, + { + "box": { + "id": "obj-52", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 380.0, + 44.0, + 22.0 + ], + "text": "== 1" + } + }, + { + "box": { + "id": "obj-53", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 920.0, + 254.0, + 22.0 + ], + "text": "test.assert console-only-the-stall" + } + }, + { + "box": { + "id": "obj-54", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 0, + "outlettype": [], + "patching_rect": [ + 20.0, + 108.0, + 114.0, + 22.0 + ], + "text": "test.terminate" + } + }, + { + "box": { + "id": "obj-55", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 410.0, + 72.0, + 22.0 + ], + "text": "tosymbol" + } + }, + { + "box": { + "id": "obj-56", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 5, + "outlettype": [ + "", + "", + "", + "", + "" + ], + "patching_rect": [ + 1020.0, + 440.0, + 177.0, + 22.0 + ], + "text": "regexp \\\" @substitute '" + } + }, + { + "box": { + "id": "obj-57", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 470.0, + 86.0, + 22.0 + ], + "text": "fromsymbol" + } + }, + { + "box": { + "id": "obj-58", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 1020.0, + 500.0, + 51.0, + 22.0 + ], + "text": "t l b" + } + }, + { + "box": { + "id": "obj-59", + "maxclass": "newobj", + "numinlets": 3, + "numoutlets": 4, + "outlettype": [ + "", + "", + "", + "" + ], + "patching_rect": [ + 1020.0, + 530.0, + 135.0, + 22.0 + ], + "text": "counter 1 1000000" + } + }, + { + "box": { + "id": "obj-60", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 560.0, + 51.0, + 22.0 + ], + "text": "<= 50" + } + }, + { + "box": { + "id": "obj-61", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 1020.0, + 590.0, + 72.0, + 22.0 + ], + "text": "gate 1 1" + } + }, + { + "box": { + "id": "obj-62", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 0, + "outlettype": [], + "patching_rect": [ + 1020.0, + 620.0, + 170.0, + 22.0 + ], + "text": "test.log console-error" + } + }, + { + "box": { + "id": "obj-63", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 138.0, + 72.0, + 22.0 + ], + "text": "loadbang" + } + }, + { + "box": { + "id": "obj-64", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 168.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-65", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 198.0, + 93.0, + 22.0 + ], + "text": "; dsp start" + } + }, + { + "box": { + "id": "obj-66", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 228.0, + 93.0, + 22.0 + ], + "text": "delay 60000" + } + }, + { + "box": { + "id": "obj-67", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 4, + "outlettype": [ + "", + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 258.0, + 79.0, + 22.0 + ], + "text": "dspstate~" + } + }, + { + "box": { + "id": "obj-68", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 288.0, + 51.0, + 22.0 + ], + "text": "sel 1" + } + }, + { + "box": { + "id": "obj-69", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 318.0, + 79.0, + 22.0 + ], + "text": "onebang 1" + } + }, + { + "box": { + "id": "obj-70", + "maxclass": "message", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 348.0, + 40.0, + 22.0 + ], + "text": "1" + } + }, + { + "box": { + "id": "obj-71", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 770.0, + 950.0, + 191.0, + 22.0 + ], + "text": "test.assert audio-started" + } + }, + { + "box": { + "id": "obj-72", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 378.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-73", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 4, + "outlettype": [ + "", + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 408.0, + 79.0, + 22.0 + ], + "text": "t b b b b" + } + }, + { + "box": { + "id": "obj-74", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 438.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-75", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 468.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-76", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 498.0, + 86.0, + 22.0 + ], + "text": "delay 1000" + } + }, + { + "box": { + "id": "obj-77", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 528.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-78", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 558.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-79", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 588.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-80", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 618.0, + 86.0, + 22.0 + ], + "text": "delay 1000" + } + }, + { + "box": { + "id": "obj-81", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 3, + "outlettype": [ + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 648.0, + 65.0, + 22.0 + ], + "text": "t b b b" + } + }, + { + "box": { + "id": "obj-82", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 678.0, + 86.0, + 22.0 + ], + "text": "delay 1000" + } + }, + { + "box": { + "id": "obj-83", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 708.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-84", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 738.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-85", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 768.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-86", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 798.0, + 79.0, + 22.0 + ], + "text": "delay 500" + } + }, + { + "box": { + "id": "obj-87", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 828.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-88", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 858.0, + 79.0, + 22.0 + ], + "text": "delay 150" + } + }, + { + "box": { + "id": "obj-89", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 888.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + }, + { + "box": { + "id": "obj-90", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 918.0, + 79.0, + 22.0 + ], + "text": "delay 500" + } + }, + { + "box": { + "id": "obj-91", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 4, + "outlettype": [ + "", + "", + "", + "" + ], + "patching_rect": [ + 20.0, + 948.0, + 79.0, + 22.0 + ], + "text": "t b b b b" + } + }, + { + "box": { + "id": "obj-92", + "maxclass": "newobj", + "numinlets": 2, + "numoutlets": 1, + "outlettype": [ + "" + ], + "patching_rect": [ + 20.0, + 978.0, + 79.0, + 22.0 + ], + "text": "delay 500" + } + }, + { + "box": { + "id": "obj-93", + "maxclass": "newobj", + "numinlets": 1, + "numoutlets": 2, + "outlettype": [ + "", + "" + ], + "patching_rect": [ + 20.0, + 1008.0, + 51.0, + 22.0 + ], + "text": "t b b" + } + } + ], + "lines": [ + { + "patchline": { + "source": [ + "obj-2", + 0 + ], + "destination": [ + "obj-3", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-2", + 0 + ], + "destination": [ + "obj-4", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-3", + 0 + ], + "destination": [ + "obj-5", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-3", + 0 + ], + "destination": [ + "obj-6", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-4", + 0 + ], + "destination": [ + "obj-5", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-2", + 0 + ], + "destination": [ + "obj-6", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-7", + 1 + ], + "destination": [ + "obj-3", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-7", + 0 + ], + "destination": [ + "obj-4", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-8", + 0 + ], + "destination": [ + "obj-9", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-9", + 2 + ], + "destination": [ + "obj-10", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-10", + 0 + ], + "destination": [ + "obj-11", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-5", + 0 + ], + "destination": [ + "obj-12", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-12", + 0 + ], + "destination": [ + "obj-13", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-14", + 1 + ], + "destination": [ + "obj-13", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-14", + 0 + ], + "destination": [ + "obj-17", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-17", + 0 + ], + "destination": [ + "obj-16", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-15", + 0 + ], + "destination": [ + "obj-13", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-13", + 0 + ], + "destination": [ + "obj-16", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-16", + 0 + ], + "destination": [ + "obj-18", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-18", + 0 + ], + "destination": [ + "obj-19", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-5", + 0 + ], + "destination": [ + "obj-20", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-20", + 0 + ], + "destination": [ + "obj-21", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-22", + 1 + ], + "destination": [ + "obj-21", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-22", + 0 + ], + "destination": [ + "obj-25", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-25", + 0 + ], + "destination": [ + "obj-24", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-23", + 0 + ], + "destination": [ + "obj-21", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-21", + 0 + ], + "destination": [ + "obj-24", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-24", + 0 + ], + "destination": [ + "obj-26", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-26", + 0 + ], + "destination": [ + "obj-27", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-28", + 1 + ], + "destination": [ + "obj-3", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-28", + 0 + ], + "destination": [ + "obj-29", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-29", + 0 + ], + "destination": [ + "obj-30", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-31", + 1 + ], + "destination": [ + "obj-3", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-31", + 0 + ], + "destination": [ + "obj-32", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-32", + 0 + ], + "destination": [ + "obj-33", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-34", + 0 + ], + "destination": [ + "obj-3", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-11", + 0 + ], + "destination": [ + "obj-35", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-35", + 0 + ], + "destination": [ + "obj-36", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-36", + 0 + ], + "destination": [ + "obj-37", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-38", + 0 + ], + "destination": [ + "obj-3", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-5", + 0 + ], + "destination": [ + "obj-39", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-39", + 0 + ], + "destination": [ + "obj-40", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-40", + 0 + ], + "destination": [ + "obj-41", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-42", + 0 + ], + "destination": [ + "obj-3", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-43", + 1 + ], + "destination": [ + "obj-3", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-43", + 0 + ], + "destination": [ + "obj-44", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-44", + 0 + ], + "destination": [ + "obj-45", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-6", + 0 + ], + "destination": [ + "obj-46", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-46", + 0 + ], + "destination": [ + "obj-47", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-47", + 0 + ], + "destination": [ + "obj-48", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-8", + 0 + ], + "destination": [ + "obj-49", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-49", + 0 + ], + "destination": [ + "obj-50", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-50", + 0 + ], + "destination": [ + "obj-51", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-51", + 0 + ], + "destination": [ + "obj-52", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-52", + 0 + ], + "destination": [ + "obj-53", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-8", + 0 + ], + "destination": [ + "obj-55", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-55", + 0 + ], + "destination": [ + "obj-56", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-56", + 0 + ], + "destination": [ + "obj-57", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-56", + 3 + ], + "destination": [ + "obj-57", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-57", + 0 + ], + "destination": [ + "obj-58", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-58", + 1 + ], + "destination": [ + "obj-59", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-59", + 0 + ], + "destination": [ + "obj-60", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-60", + 0 + ], + "destination": [ + "obj-61", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-58", + 0 + ], + "destination": [ + "obj-61", + 1 + ] + } + }, + { + "patchline": { + "source": [ + "obj-61", + 0 + ], + "destination": [ + "obj-62", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-63", + 0 + ], + "destination": [ + "obj-64", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-64", + 1 + ], + "destination": [ + "obj-66", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-64", + 0 + ], + "destination": [ + "obj-65", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-66", + 0 + ], + "destination": [ + "obj-54", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-67", + 0 + ], + "destination": [ + "obj-68", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-68", + 0 + ], + "destination": [ + "obj-69", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-69", + 0 + ], + "destination": [ + "obj-70", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-70", + 0 + ], + "destination": [ + "obj-71", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-69", + 0 + ], + "destination": [ + "obj-72", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-72", + 0 + ], + "destination": [ + "obj-73", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-73", + 3 + ], + "destination": [ + "obj-28", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-73", + 2 + ], + "destination": [ + "obj-7", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-73", + 1 + ], + "destination": [ + "obj-31", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-73", + 0 + ], + "destination": [ + "obj-74", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-74", + 0 + ], + "destination": [ + "obj-75", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-75", + 1 + ], + "destination": [ + "obj-14", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-75", + 0 + ], + "destination": [ + "obj-76", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-76", + 0 + ], + "destination": [ + "obj-77", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-77", + 1 + ], + "destination": [ + "obj-15", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-77", + 0 + ], + "destination": [ + "obj-78", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-78", + 0 + ], + "destination": [ + "obj-79", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-79", + 1 + ], + "destination": [ + "obj-34", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-79", + 0 + ], + "destination": [ + "obj-80", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-80", + 0 + ], + "destination": [ + "obj-81", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-81", + 2 + ], + "destination": [ + "obj-35", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-81", + 1 + ], + "destination": [ + "obj-22", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-81", + 0 + ], + "destination": [ + "obj-82", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-82", + 0 + ], + "destination": [ + "obj-83", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-83", + 1 + ], + "destination": [ + "obj-23", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-83", + 0 + ], + "destination": [ + "obj-84", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-84", + 0 + ], + "destination": [ + "obj-85", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-85", + 1 + ], + "destination": [ + "obj-38", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-85", + 0 + ], + "destination": [ + "obj-86", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-86", + 0 + ], + "destination": [ + "obj-87", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-87", + 1 + ], + "destination": [ + "obj-39", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-87", + 0 + ], + "destination": [ + "obj-88", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-88", + 0 + ], + "destination": [ + "obj-89", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-89", + 1 + ], + "destination": [ + "obj-42", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-89", + 0 + ], + "destination": [ + "obj-90", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-90", + 0 + ], + "destination": [ + "obj-91", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-91", + 3 + ], + "destination": [ + "obj-43", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-91", + 2 + ], + "destination": [ + "obj-46", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-91", + 1 + ], + "destination": [ + "obj-51", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-91", + 0 + ], + "destination": [ + "obj-92", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-92", + 0 + ], + "destination": [ + "obj-93", + 0 + ] + } + }, + { + "patchline": { + "source": [ + "obj-93", + 1 + ], + "destination": [ + "obj-54", + 0 + ] + } + } + ] + } +} diff --git a/runtime-tests/python/maxtest_stall.py b/runtime-tests/python/maxtest_stall.py new file mode 100644 index 0000000..cff5aae --- /dev/null +++ b/runtime-tests/python/maxtest_stall.py @@ -0,0 +1,13 @@ +# Runtime-test fixture (runtime-tests/run.py copies it into python/): passes its input through, but +# can be told to stall once — a worker falling behind (plan 2.5). +import time + + +class maxtest_stall: + stall: float = 0.0 # seconds to sleep at the next sample, once + + def process(self, x: float) -> float: + if self.stall: + seconds, self.stall = self.stall, 0.0 + time.sleep(seconds) + return x diff --git a/runtime-tests/run.py b/runtime-tests/run.py index e3ded73..0b680d7 100644 --- a/runtime-tests/run.py +++ b/runtime-tests/run.py @@ -360,7 +360,8 @@ def check_prerequisites(max_app: Path, packages: Path) -> None: raise RunError("the external is not built — cmake -S . -B build && cmake --build build" if PACKAGE == ROOT else f"no external in {PACKAGE}") binary = EXTERNAL / "Contents" / "MacOS" / "tap.python~" - sources = [f for folder in ("core/include", "source/projects") for f in (ROOT / folder).rglob("*") if f.is_file()] + sources = [f for folder in ("core/include", "source/projects") for f in (ROOT / folder).rglob("*") + if f.is_file() and not f.name.endswith("_test.cpp")] # the mock test is not in the external newest = max(sources, key=lambda f: f.stat().st_mtime) built_here = EXTERNAL.resolve().is_relative_to(ROOT) # not an installed release's if built_here and binary.exists() and newest.stat().st_mtime > binary.stat().st_mtime: # after switching branches diff --git a/source/projects/tap.python_tilde/tap.python_tilde.h b/source/projects/tap.python_tilde/tap.python_tilde.h index 5f3ae34..fd6f8d5 100644 --- a/source/projects/tap.python_tilde/tap.python_tilde.h +++ b/source/projects/tap.python_tilde/tap.python_tilde.h @@ -8,12 +8,14 @@ #include "tap/python/processor.h" #include "tap/python/runtime.h" #include "tap/python/value.h" +#include "tap/python/worker.h" // c74_min.h must be the FIRST min header in the translation unit: it defines // C74_MIN_WITH_IMPLEMENTATION so the min wrapper's out-of-line statics get // emitted here. If c74_min_api.h sneaks in first (e.g. via our helper headers), // the include guards swallow those definitions and the external fails to link. #include +#include #include #include #include @@ -21,6 +23,12 @@ #include #include "c74_min.h" +#if defined(__APPLE__) +#include +#include +#include +#include +#endif #include "tap.python_tilde_attribute.h" #include "tap.python_tilde_cglue.h" #include "tap.python_tilde_filewatch.h" @@ -44,7 +52,9 @@ class python : public object, public vector_operator<> { "float; its parameters are the object's signal inlets, and its return hint its outlets " "(a tuple of values for more than one). An optional prepare(sample_rate, vector_size) " "method receives the audio settings " - "before audio starts and whenever they change. The file is watched and reloaded when saved, " + "before audio starts and whenever they change. With @mode worker, process() runs on a thread of " + "its own, @latency milliseconds behind the audio, so that nothing else Python does can hold " + "the audio up. The file is watched and reloaded when saved, " "keeping attribute values; a save that changes process()'s inputs or outputs changes the " "inlets and outlets to match, keeping the patch cords of those that stay. Errors are " "printed to the Max console and never take Max down."}; @@ -88,6 +98,7 @@ class python : public object, public vector_operator<> { if (m_processor) { try { m_processor->flush_reports(); + m_worker->flush_reports(); } catch (const std::exception& e) { cerr << "reporting failed: " << e.what() << endl; @@ -102,17 +113,53 @@ class python : public object, public vector_operator<> { message<> dspsetup{this, "dspsetup", MIN_FUNCTION { if (m_processor) { + const auto sample_rate = static_cast(args[0]); + const auto vector_size = static_cast(static_cast(args[1])); try { - m_processor->prepare(static_cast(args[0]), - static_cast(static_cast(args[1]))); + m_processor->prepare(sample_rate, vector_size); } catch (const std::exception& e) { cerr << "prepare failed: " << e.what() << endl; } + set_up_worker(sample_rate, vector_size); } return {}; }}; + // Worker mode (plan 2.5): where process() runs, and how far behind. Both take effect when the + // signal chain compiles; setting either rebuilds it, so that is at once while audio runs. + attribute m_mode{this, + "mode", + "direct", + description{"Where process() runs: direct, on the audio thread, with no latency; or " + "worker, on a thread of its own, about latency milliseconds behind, so that " + "nothing Python does elsewhere (a reload, a message, a garbage " + "collection) can hold up the audio."}, + range{"direct", "worker"}, + c74::min::setter{MIN_FUNCTION { + const bool worker = !args.empty() && args[0] == symbol("worker"); + rebuild_signal_chain(); + return {symbol(worker ? "worker" : "direct")}; + }}}; + attribute m_latency{this, + "latency", + runtime::worker::k_default_latency_ms, + description{"The latency in worker mode, in milliseconds (0 to 1000), rounded up " + "to whole signal vectors, at least one. It must be longer than Max's I/O " + "vector, which Max computes all at once: what is left over is the time " + "Python has to keep up. More absorbs longer pauses, at the cost of " + "delay."}, + range{0.0, 1000.0}, + c74::min::setter{MIN_FUNCTION { + rebuild_signal_chain(); + return {std::clamp(static_cast(args[0]), 0.0, 1000.0)}; + }}}; + attribute m_latencysamples{this, "latencysamples", 0, + description{"The delay worker mode adds, in samples (latency rounded up to " + "whole signal vectors), for aligning other signal paths; 0 in " + "direct mode or with audio off."}, + readonly{true}}; + python(const atoms& args = {}) { if (maxobj() == NULL) { return; // this occurs during dummy construction @@ -157,17 +204,18 @@ class python : public object, public vector_operator<> { : to_string(args); } - m_processor = std::make_unique( - m_python_source, - [this](const runtime::log_level level, const std::string_view text) { - if (level == runtime::log_level::error) { - cerr << std::string{text} << endl; - } - else { - cout << std::string{text} << endl; - } - }, - reserved_messages(), [this] { m_reports.set(); }); + const auto object_log = [this](const runtime::log_level level, const std::string_view text) { + if (level == runtime::log_level::error) { + cerr << std::string{text} << endl; + } + else { + cout << std::string{text} << endl; + } + }; + m_processor = std::make_unique(m_python_source, object_log, reserved_messages(), + [this] { m_reports.set(); }); + m_worker = std::make_unique( + *m_processor, object_log, [this] { m_reports.set(); }, audio_thread_scheduling); update_source(); create_ports(); // before min makes the Max inlets and outlets from its lists, after this @@ -193,6 +241,8 @@ class python : public object, public vector_operator<> { ~python() { m_file_watch.reset(); + m_use_worker = false; + m_worker.reset(); // joins the worker thread, before the processor it runs goes m_processor.reset(); // releases the Python objects under the GIL } @@ -288,9 +338,15 @@ class python : public object, public vector_operator<> { } try { // every channel Max gives: the core matches them to what process() declares (plan 2.4) - m_processor->process(input.samples(), static_cast(input.channel_count()), output.samples(), - static_cast(output.channel_count()), - static_cast(input.frame_count())); + const auto inputs = static_cast(input.channel_count()); + const auto outputs = static_cast(output.channel_count()); + const auto frames = static_cast(input.frame_count()); + if (m_use_worker.load(std::memory_order_acquire)) { // never takes the GIL (plan 2.5) + m_worker->process(input.samples(), inputs, output.samples(), outputs, frames); + } + else { + m_processor->process(input.samples(), inputs, output.samples(), outputs, frames); + } } catch (...) { // never let an exception unwind into the audio driver output.clear(); @@ -298,24 +354,58 @@ class python : public object, public vector_operator<> { } private: - string m_python_source{}; - std::filesystem::path m_scripts_dir{}; - std::unique_ptr m_file_watch; - std::unique_ptr m_processor; - std::vector>> m_more_inlets; // after the first - std::vector>> m_more_outlets; // after the first - bool m_ports_made{}; - bool m_ports_differ{}; + string m_python_source{}; + std::filesystem::path m_scripts_dir{}; + std::unique_ptr m_file_watch; + std::unique_ptr m_processor; + std::unique_ptr m_worker; // runs m_processor + std::atomic m_use_worker{}; // read by the audio thread + std::vector>> m_more_inlets; // after the first + std::vector>> m_more_outlets; // after the first + bool m_ports_made{}; + bool m_ports_differ{}; std::unordered_map> m_python_messages; std::unordered_map> m_python_attributes; - /// Messages the Max object handles itself, which a Python method must never replace: min's - /// own class methods, the messages Max sends every object, and this object's file watcher - /// (a Python method named filechanged would silently disable hot reload). + /// Messages and attributes the Max object handles itself, which a Python method or field must + /// never replace: min's own class methods, the messages Max sends every object, this object's + /// file watcher (a Python method named filechanged would silently disable hot reload), and its + /// own attributes (worker mode's, plan 2.5). static std::vector reserved_messages() { - return {"anything", "appendtodictionary", "assist", "dblclick", "dsp", "dsp64", - "dspsetup", "filechanged", "getvalueof", "inletinfo", "loadbang", "notify", - "preset", "savestate", "setvalueof", "signal"}; + return {"anything", "appendtodictionary", "assist", "dblclick", "dsp", + "dsp64", "dspsetup", "filechanged", "getvalueof", "inletinfo", + "latency", "latencysamples", "loadbang", "mode", "notify", + "preset", "savestate", "setvalueof", "signal"}; + } + + /// The worker thread's scheduling (plan 2.5): the real-time class an audio thread has, so that a + /// busy machine does not hold it off for longer than its latency (measured in Max: an ordinary + /// thread was late even with 32 vectors of latency). On the worker thread as it starts, with the + /// vector period in seconds. If the system refuses, the thread keeps ordinary scheduling. + static void audio_thread_scheduling(const double period) { +#if defined(__APPLE__) + // Mach's time-constraint policy, in Mach absolute time: the thread runs once a period, needs + // up to half of it, and must be done within it + if (period <= 0.0) { + return; + } + mach_timebase_info_data_t timebase{}; + if (mach_timebase_info(&timebase) != KERN_SUCCESS || timebase.numer == 0) { + return; + } + const double ticks = period * 1e9 * timebase.denom / timebase.numer; + thread_time_constraint_policy_data_t policy{}; + policy.period = static_cast(ticks); + policy.computation = static_cast(ticks / 2); + policy.constraint = static_cast(ticks); + policy.preemptible = 1; + thread_policy_set(pthread_mach_thread_np(pthread_self()), THREAD_TIME_CONSTRAINT_POLICY, + reinterpret_cast(&policy), THREAD_TIME_CONSTRAINT_POLICY_COUNT); +#elif defined(_WIN32) + SetThreadPriority(GetCurrentThread(), THREAD_PRIORITY_TIME_CRITICAL); +#else + (void)period; // Linux development builds: no host runs there +#endif } /// Python's print() output and tracebacks, for every instance. @@ -427,11 +517,37 @@ class python : public object, public vector_operator<> { c74::max::object_method(box, c74::max::gensym("dynlet_end")); m_ports_differ = false; + rebuild_signal_chain(); + } + + /// Have Max rebuild the signal chain this object is in (as it does when patch cords change), + /// which calls dspsetup again: after its inlets or outlets change, or worker mode's settings. + void rebuild_signal_chain() { + if (maxobj() == nullptr) { + return; + } if (auto* chain = c74::max::dspchain_fromobject(maxobj())) { c74::max::dspchain_setbroken(chain); } } + /// Start the worker for the chain being compiled — this object's inlets and outlets, the + /// vector size, @latency — or stop it in direct mode. Main thread, from dspsetup; the old chain + /// may still be running, which the worker allows for (plan 2.5). + void set_up_worker(const double sample_rate, const std::size_t vector_size) { + if (m_mode.get() == symbol("worker")) { + m_worker->start(1 + m_more_inlets.size(), 1 + m_more_outlets.size(), vector_size, + runtime::worker::latency_vectors(m_latency, sample_rate, vector_size), sample_rate); + m_use_worker.store(true, std::memory_order_release); + } + else { + m_use_worker.store(false, std::memory_order_release); + m_worker->stop(); + } + // set directly (not through Max, which refuses to set a readonly attribute), overriding readonly + m_latencysamples.set({static_cast(m_worker->latency_samples())}, false, true); + } + /// min's lists of this object's inlets and outlets, one entry for each the Max object has: /// min's dsp64 reads a connection count for each, and its assist the help text, which names /// each inlet for its process() parameter. They make no Max inlets or outlets after the diff --git a/source/projects/tap.python_tilde/tap.python_tilde_test.cpp b/source/projects/tap.python_tilde/tap.python_tilde_test.cpp index 2e76b5f..9321a78 100644 --- a/source/projects/tap.python_tilde/tap.python_tilde_test.cpp +++ b/source/projects/tap.python_tilde/tap.python_tilde_test.cpp @@ -2,9 +2,11 @@ /// @copyright Copyright 2022-2026 Timothy Place. All rights reserved. /// @license Use of this source code is governed by the MIT License found in the License.md file. +#include #include #include #include +#include #include #include "c74_min_unittest.h" // required unit-test header (defines main via Catch) @@ -411,3 +413,46 @@ SCENARIO("A save that changes process()'s inputs or outputs changes the object's c74::max::object_free(wrapped); std::filesystem::remove(file); } + +SCENARIO("With @mode worker, process() runs on a thread of its own, @latency milliseconds behind (plan 2.5)") { + ext_main(nullptr); + test_wrapper an_instance; + python& my_object = an_instance; + REQUIRE(Py_IsInitialized()); + + my_object.m_mode = c74::min::symbol("worker"); + my_object.m_latency = 4.0; // three 64-sample vectors at 48 kHz + my_object.dspsetup(c74::min::atoms{48000.0, 64}); // as min does when the chain compiles + THEN("the delay it adds is reported in samples") { + CHECK(static_cast(my_object.m_latencysamples) == 3 * 64); + } + THEN("the output is the input three vectors later, the first three silence") { + for (int k = 0; k < 6; ++k) { + const auto out = render(my_object, static_cast(k + 1)); + CHECK(all_equal(out, k < 3 ? 0.0 : static_cast(k - 3 + 1))); + std::this_thread::sleep_for(std::chrono::milliseconds{50}); // the worker's turn + } + } + WHEN("the mode is set back to direct and the chain compiles") { + my_object.m_mode = c74::min::symbol("direct"); + my_object.dspsetup(c74::min::atoms{48000.0, 64}); + THEN("there is no delay") { + CHECK(static_cast(my_object.m_latencysamples) == 0); + CHECK(all_equal(render(my_object, 0.5), 0.5)); + } + } + WHEN("the mode is set to something else") { + my_object.m_mode = c74::min::symbol("fast"); + THEN("it is direct") { + CHECK(my_object.m_mode.get() == c74::min::symbol("direct")); + } + } + WHEN("the latency is set below 0") { + my_object.m_latency = -1.0; + my_object.dspsetup(c74::min::atoms{48000.0, 64}); + THEN("it is held to 0, which is one vector") { + CHECK(static_cast(my_object.m_latency) == 0.0); + CHECK(static_cast(my_object.m_latencysamples) == 64); + } + } +} From efbf884705640b2681ce8d6a17a77bcb972238e2 Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Thu, 1 Oct 2026 06:42:47 -0500 Subject: [PATCH 13/15] Plan: 2.5 done; the help patcher mentions worker mode Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- docs/PRODUCTION-PLAN.md | 4 ++-- help/tap.python~.maxhelp | 15 ++++++++++++++- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index 3eededb..a3154a7 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -130,7 +130,7 @@ while audio ran segfaulted in 5 of 5 runs. the class; runtime test `channels`: grown from two to three, the old cords carry on and cords that `thispatcher` connects to the new inlet and outlet carry signal (this check fails against (b)); shrunk to one, the removed outlets' cords go with them. -- [ ] **2.5 Worker mode (D1)** — `@mode worker`: Python on a worker thread, lock-free FIFO, +- [x] **2.5 Worker mode (D1)** — `@mode worker`: Python on a worker thread, lock-free FIFO, latency reported to Max, underrun → silence. *Design (decided 2026-09-30):* - **What it buys.** In direct mode the audio thread takes the GIL, so anything else holding it — a reload compiling a large file (2.6's limit), a message handler, a GC pass — delays the @@ -185,7 +185,7 @@ while audio ran segfaulted in 5 of 5 runs. reload; a stall past the ring drops exactly the vectors beyond it; restart, stop, and stop during a stall; ten reloads under an audio thread. Clean under TSan (locally, macOS) — the Linux CI job runs it too. *(b) the Max object:* `@mode`, `@latency`, `@latencysamples`, the - ring sized in `dspsetup`; runtime test in Max. *Found in Max:* an ordinary worker thread was + ring sized in `dspsetup`; runtime test in Max — *done*. *Found in Max:* an ordinary worker thread was late for vectors in 2 of 5 quiet seconds even with 32 vectors (21 ms) of latency, on a busy machine (load average 6–11); the worker now gets the real-time scheduling of an audio thread — a hook the core calls on the thread as it starts (`thread_setup`), where the wrapper sets diff --git a/help/tap.python~.maxhelp b/help/tap.python~.maxhelp index 41e1fcf..a69be96 100644 --- a/help/tap.python~.maxhelp +++ b/help/tap.python~.maxhelp @@ -10,7 +10,7 @@ } , "classnamespace" : "box", - "rect" : [ 100.0, 100.0, 780.0, 650.0 ], + "rect" : [ 100.0, 100.0, 780.0, 700.0 ], "bglocked" : 0, "openinpresentation" : 0, "default_fontsize" : 13.0, @@ -364,6 +364,19 @@ "text" : "process()'s parameters are the object's signal inlets and its return hint its outlets: [tap.python~ stereo_width] has two of each. A save that changes them changes the object's inlets and outlets." } + } +, { + "box" : { + "fontsize" : 13.0, + "id" : "obj-42", + "linecount" : 3, + "maxclass" : "comment", + "numinlets" : 1, + "numoutlets" : 0, + "patching_rect" : [ 270.0, 595.0, 300.0, 62.0 ], + "text" : "@mode worker runs process() on a thread of its own, @latency milliseconds (30) behind, so a reload or a message never holds up the audio." + } + } , { "box" : { From ce98cf81b6bee0751475c4e00f9f283ad70589d3 Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Thu, 1 Oct 2026 07:06:28 -0500 Subject: [PATCH 14/15] =?UTF-8?q?4.7:=20uv,=20evaluated=20=E2=80=94=20docu?= =?UTF-8?q?mented=20where=20it=20helps,=20not=20adopted=20where=20it=20wou?= =?UTF-8?q?ld=20not?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- CLAUDE.md | 3 ++- ReadMe.md | 3 ++- docs/PRODUCTION-PLAN.md | 15 +++++++++++++-- 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 60cebde..9999384 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -60,7 +60,8 @@ its phases, and the audit findings behind them. Tick its items (with the PR) as ## Build & test -The fast loop is Linux, no Max and no runtime install needed — just a CPython 3.13 with headers: +The fast loop is Linux, no Max and no runtime install needed — just a CPython 3.13 with headers +(without one, `uv python install 3.13`, then `-DPython3_EXECUTABLE=$(uv python find 3.13)`): ```sh # the core battery diff --git a/ReadMe.md b/ReadMe.md index 0b5fe84..1137084 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -56,6 +56,7 @@ To add more Python packages to the bundled runtime: ./support/bin/python3 -m pip install # macOS, from the package folder .\support\python.exe -m pip install # Windows ``` +If you use [uv](https://docs.astral.sh/uv/), `uv pip install --python support/bin/python3 ` (or `support\python.exe` on Windows) does the same, faster; nothing in the package needs uv. ### From a clone of this repository @@ -175,7 +176,7 @@ cmake --build build-core ctest --test-dir build-core --output-on-failure ``` -The example tests need `attrs` and `numpy` importable by that interpreter (or in a folder named by `TAP_PYTHON_TEST_SITE`); without them they are skipped. `-DTAP_PYTHON_SANITIZE=address,undefined` or `=thread` builds the battery under sanitizers, as CI does. +Any CPython 3.13 with its headers will do; if you have no `python3.13`, `uv python install 3.13` gets one, and `$(uv python find 3.13)` names it. The example tests need `attrs` and `numpy` importable by that interpreter (or in a folder named by `TAP_PYTHON_TEST_SITE`); without them they are skipped. `-DTAP_PYTHON_SANITIZE=address,undefined` or `=thread` builds the battery under sanitizers, as CI does. The core's build also makes `core/bench`, which times `process()` as Max's audio thread calls it; `python3 scripts/update-perf-docs.py` builds it (Release), runs it, and rewrites the tables in [the performance note](#a-note-on-performance) — with `--max`, the table measured in Max too. Measure on an idle machine; never edit those tables by hand. diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index a3154a7..eff8ac4 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -308,7 +308,7 @@ while audio ran segfaulted in 5 of 5 runs. ships — Min-API, the Max SDK, CPython's, and each installed package's own (PEP 639 `dist-info/licenses/`, where numpy lists what it bundles) — with an index, collected from the package's actual contents; CI runs the collection on Linux. -- [ ] **4.7 uv for development and release tooling** — *Discussed (2026-09-30):* use uv where it +- [x] **4.7 uv for development and release tooling** — *Discussed (2026-09-30):* use uv where it replaces work we do by hand; keep the shipped runtime a python-build-standalone archive pinned by SHA256 in `runtime.lock`. For uv: `uv pip compile --universal --generate-hashes` in place of most of `update-locks.py`'s PyPI handling; `uv pip install --python-platform --target …` @@ -318,7 +318,18 @@ while audio ran segfaulted in 5 of 5 runs. version, installs in its own layout, and may mark the interpreter externally managed (to check) — and the work that matters (the `@rpath` install name, re-signing, the universal libpython) is ours either way. Users never need uv; the ReadMe may mention - `uv pip install --python support/bin/python3 …` beside pip. + `uv pip install --python support/bin/python3 …` beside pip. *Evaluated (2026-10-01, uv 0.12.21), + and it came down to documentation:* `uv pip compile --generate-hashes` lists every distribution + of each pin — 68 hashes for attrs and numpy, every Python version and platform, even with + `--python-platform` — where `update-locks.py` pins exactly the 8 wheels we ship, so it stays; + 4.8 can merge the platform builds CI already makes, so it needs no cross-platform install + (which does work: Windows' numpy wheels installed on a Mac against our lock, hashes enforced); + the scripts use only the standard library, so `uv run` adds nothing; and `uv python install` + marks its interpreter `EXTERNALLY-MANAGED` (pip then refuses to install into it) and installed + 3.13.15 against our pinned 3.13.14 — confirming the runtime stays ours. What uv is good for here + is now documented: `uv python install 3.13` for the Linux loop's CPython with headers (ReadMe, + CLAUDE.md), and `uv pip install --python support/bin/python3` for users adding packages to the + runtime (it is not externally managed). - [ ] **4.8 One package for every platform on each tag** — *Decided (2026-09-30):* a tag also attaches a single `PythonTap-.zip` holding every platform's external and runtime, and v0.x tags publish as pre-releases automatically (1.0 and later stay drafts until signing From 24c54222f2e233393ade96d06696d5a1bb8c70aa Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Thu, 1 Oct 2026 07:17:00 -0500 Subject: [PATCH 15/15] 4.8: one package for every platform on each tag A tag now also attaches PythonTap-.zip, holding the macOS and Windows externals and each platform's runtime in support/. The external uses support/ 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-/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/ and each platform's licenses in licenses/. 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) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- .github/workflows/release.yml | 61 ++++++-- CHANGELOG.md | 8 ++ CLAUDE.md | 4 +- ReadMe.md | 7 +- docs/PRODUCTION-PLAN.md | 16 ++- scripts/assemble-package.py | 133 +++++++++++++++++- .../projects/tap.python_tilde/CMakeLists.txt | 12 ++ .../tap.python_tilde/tap.python_tilde.h | 2 +- .../tap.python_tilde_package.h | 23 +++ .../tap.python_tilde_test.cpp | 23 +++ 10 files changed, 273 insertions(+), 16 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 72bf9e3..c47d6be 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,10 +1,14 @@ name: release # Builds the release packages (plan 4.5, D3): the Max package with the runtime bundled, per -# platform, zipped with SHA256 checksums, and attached to a *draft* GitHub release for a tag -# vMAJOR.MINOR.PATCH — publishing it stays a deliberate act. Run by hand (workflow_dispatch), it -# builds and uploads the packages as workflow artifacts without making a release. +# platform and for every platform at once (plan 4.8), zipped with SHA256 checksums, and attached +# to a GitHub release for a tag vMAJOR.MINOR.PATCH: published as a pre-release for 0.x versions, +# and a *draft* from 1.0 on — publishing those stays a deliberate act until the packages are +# signed. Run by hand (workflow_dispatch), it builds and uploads the packages as workflow artifacts +# without making a release. # +# PythonTap-.zip every platform: both externals, and each runtime in +# support/, where the external looks first # PythonTap--macos-arm64.zip universal external + the Apple Silicon runtime # PythonTap--macos-x86_64.zip universal external + the Intel runtime (and for Max # running under Rosetta) @@ -194,12 +198,50 @@ jobs: path: dist/*.zip* if-no-files-found: error + # One package for every platform (plan 4.8), merged from the three just built: each runtime in + # support/, each platform's licenses in licenses/, the rest once. + all-platforms: + name: all platforms + needs: [macos, windows] + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 + + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + pattern: package-* + path: platforms + merge-multiple: true + + - name: Merge + run: | + set -euo pipefail + args=() + version="" + for zip in platforms/PythonTap-*.zip; do + [[ "$(basename "$zip")" =~ ^PythonTap-([0-9][0-9.]*)-(macos-arm64|macos-x86_64|windows-x64)\.zip$ ]] \ + || { echo "::error::unexpected package $zip"; exit 1; } + version="${BASH_REMATCH[1]}" + args+=("${BASH_REMATCH[2]}=$zip") + done + [[ ${#args[@]} -eq 3 ]] || { echo "::error::expected 3 platform packages, found ${#args[@]}"; exit 1; } + python3 scripts/assemble-package.py --merge "${args[@]}" --output dist + name="PythonTap-$version.zip" + (cd dist && zip -qry "$name" PythonTap && sha256sum "$name" > "$name.sha256") + ls -la dist + + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: package-all + path: dist/*.zip* + if-no-files-found: error + release: if: github.ref_type == 'tag' - needs: [macos, windows] + needs: [macos, windows, all-platforms] runs-on: ubuntu-latest permissions: - contents: write # create the draft release; nothing else in this workflow can write + contents: write # create the release; nothing else in this workflow can write steps: - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 with: @@ -215,10 +257,13 @@ jobs: sha256sum *.zip > SHA256SUMS for f in *.zip.sha256; do sha256sum -c "$f"; done - - name: Create the draft release + # 0.x: published at once, as a pre-release (plan 4.8); from 1.0, a draft to publish by hand + - name: Create the release env: GH_TOKEN: ${{ github.token }} run: | + version="${GITHUB_REF_NAME#v}" + if [[ "$version" == 0.* ]]; then kind=(--prerelease); else kind=(--draft); fi gh release create "$GITHUB_REF_NAME" dist/*.zip dist/*.zip.sha256 dist/SHA256SUMS \ - --repo "$GITHUB_REPOSITORY" --draft --verify-tag --title "PythonTap ${GITHUB_REF_NAME#v}" \ - --notes "See CHANGELOG.md for what changed. Unzip into Documents/Max 9/Packages; the Python runtime is included. On a Mac, choose arm64 for Apple Silicon or x86_64 for Intel (or for Max running under Rosetta)." + --repo "$GITHUB_REPOSITORY" "${kind[@]}" --verify-tag --title "PythonTap $version" \ + --notes "See CHANGELOG.md for what changed. Unzip into Documents/Max 9/Packages; the Python runtime is included. PythonTap-$version.zip works on every platform; the others are smaller, one platform each — on a Mac, arm64 for Apple Silicon or x86_64 for Intel (or for Max running under Rosetta)." diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b7bb26..c686462 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,14 @@ breaking changes to the contract are allowed where they buy correctness (D5 in ## Unreleased +### Added — one package for every platform + +- **Each release also has `PythonTap-.zip`, for every platform at once**: the macOS and + Windows externals, and each platform's runtime in `support//`. The external uses + `support//` when its package has one — on macOS, each architecture its own — and + `support/` otherwise, so the per-platform packages and a checkout work as before. 0.x releases + are published as pre-releases rather than drafts. (Plan 4.8.) + ### Added — worker mode - **`@mode worker` runs `process()` on a thread of its own**, `@latency` milliseconds behind the diff --git a/CLAUDE.md b/CLAUDE.md index 9999384..dadcd0c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -94,7 +94,9 @@ clang-format, clang-tidy (a clang-tidy failure or crash fails the gate, not just run with `contents: read`, pin third-party actions by commit SHA (tag noted beside it), and cancel superseded runs. `release.yml`: on a `vX.Y.Z` tag, builds, tests, packages (macOS per architecture, on runners of that architecture — the runtime is per arch, only libpython is universal), signs when -the secrets exist, and attaches zips + SHA256s to a draft release. +the secrets exist, merges the three into one package for every platform (`assemble-package.py +--merge`: each runtime in `support/`, where the external looks before `support/`), and +attaches all the zips + SHA256s to a release — a pre-release for 0.x, a draft from 1.0. ## Threads and the GIL (load-bearing) diff --git a/ReadMe.md b/ReadMe.md index 1137084..b6926ea 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -37,8 +37,9 @@ class default: ## Installation -Download the package for your platform from the [releases page](https://github.com/tap/PythonTap/releases) — the Python runtime (CPython 3.13 with `attrs` and `numpy`) is included: +Download a package from the [releases page](https://github.com/tap/PythonTap/releases) — the Python runtime (CPython 3.13 with `attrs` and `numpy`) is included: +- `PythonTap-.zip` — every platform at once: Apple Silicon and Intel Macs and Windows, each with its own runtime (in `support/macos-arm64`, `support/macos-x86_64` and `support/windows-x64`). The largest; the one to use when a patch travels between machines. - `PythonTap--macos-arm64.zip` — Apple Silicon Macs. - `PythonTap--macos-x86_64.zip` — Intel Macs, and Apple Silicon Macs running Max under Rosetta. - `PythonTap--windows-x64.zip` — Windows. @@ -56,7 +57,7 @@ To add more Python packages to the bundled runtime: ./support/bin/python3 -m pip install # macOS, from the package folder .\support\python.exe -m pip install # Windows ``` -If you use [uv](https://docs.astral.sh/uv/), `uv pip install --python support/bin/python3 ` (or `support\python.exe` on Windows) does the same, faster; nothing in the package needs uv. +In the package for every platform, the runtime is in `support//` — `./support/macos-arm64/bin/python3`, say, or `.\support\windows-x64\python.exe` — and a package you add goes into that platform's runtime only. If you use [uv](https://docs.astral.sh/uv/), `uv pip install --python support/bin/python3 ` (or `support\python.exe` on Windows) does the same, faster; nothing in the package needs uv. ### From a clone of this repository @@ -164,7 +165,7 @@ On Windows, configure with `cmake -S . -B build -A x64`. ### Making a release -Push a tag `vMAJOR.MINOR.PATCH`: `.github/workflows/release.yml` builds and tests on each platform (both Mac architectures on their own runners), assembles the package with `scripts/assemble-package.py` (the platform's externals, help, docs, examples, the runtime, and `licenses/`), zips it with SHA256 checksums, and attaches everything to a **draft** release to review and publish. The package version comes from the tag (min reads it from git; the assembly checks they agree). Running the workflow by hand builds the zips as workflow artifacts without a release. It signs and notarizes the Mac packages and signs the Windows binaries when the signing secrets it lists are set, and skips signing, with a warning, when they are not. +Push a tag `vMAJOR.MINOR.PATCH`: `.github/workflows/release.yml` builds and tests on each platform (both Mac architectures on their own runners), assembles the package with `scripts/assemble-package.py` (the platform's externals, help, docs, examples, the runtime, and `licenses/`), zips it with SHA256 checksums, merges the three into one package for every platform (`assemble-package.py --merge`: each runtime in `support/`, each platform's licenses in `licenses/`), and attaches everything to a release — published as a pre-release for a 0.x version, and a **draft** to review and publish from 1.0 on. The package version comes from the tag (min reads it from git; the assembly checks they agree). Running the workflow by hand builds the zips as workflow artifacts without a release. It signs and notarizes the Mac packages and signs the Windows binaries when the signing secrets it lists are set, and skips signing, with a warning, when they are not. ### The core, and testing it on Linux diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index eff8ac4..9092f97 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -330,7 +330,7 @@ while audio ran segfaulted in 5 of 5 runs. is now documented: `uv python install 3.13` for the Linux loop's CPython with headers (ReadMe, CLAUDE.md), and `uv pip install --python support/bin/python3` for users adding packages to the runtime (it is not externally managed). -- [ ] **4.8 One package for every platform on each tag** — *Decided (2026-09-30):* a tag also +- [x] **4.8 One package for every platform on each tag** — *Decided (2026-09-30):* a tag also attaches a single `PythonTap-.zip` holding every platform's external and runtime, and v0.x tags publish as pre-releases automatically (1.0 and later stay drafts until signing exists). Needs one runtime per platform side by side — `support/macos-arm64/`, @@ -340,7 +340,19 @@ while audio ran segfaulted in 5 of 5 runs. Windows external loading `python313.dll` from its folder by full path before the first delay-loaded call (Max adds only `support/` itself to the DLL search path); and a last `release.yml` job that merges the platform builds into one `PythonTap/` and attaches it with - its checksum (about 130 MB, against 37–55 MB per platform zip today). + its checksum (about 130 MB, against 37–55 MB per platform zip today). *Done:* the external + takes `support/` when it exists and `support/` otherwise + (`runtime_home()`, mock-tested); the universal macOS external carries an rpath per slice to + `support/macos-/lib` ahead of `support/lib` (`-Xarch_`, for each architecture + built); Windows already loaded the DLL by full path from the runtime folder. + `assemble-package.py --merge platform=zip …` unzips each release zip 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 (compared with line endings aside: a Windows checkout has CRLF), + every external, each runtime into `support/` and each platform's licenses into + `licenses/`; the `all platforms` job runs it on the three zips, and the release job + attaches the result, publishing 0.x tags as pre-releases. Checked in Max: a merged package + holding the Intel runtime as `support/macos-x86_64`, installed in Packages, passed the whole + runtime suite (including the sessions that move the runtime aside). ## Phase 5 — documentation and examples diff --git a/scripts/assemble-package.py b/scripts/assemble-package.py index c0f7f36..bc6a84d 100644 --- a/scripts/assemble-package.py +++ b/scripts/assemble-package.py @@ -17,6 +17,14 @@ collects just the licenses (how CI exercises it on Linux, against any installed runtime). + python3 scripts/assemble-package.py --merge macos-arm64=PythonTap-1.0.0-macos-arm64.zip \ + macos-x86_64=PythonTap-1.0.0-macos-x86_64.zip windows-x64=PythonTap-1.0.0-windows-x64.zip \ + --output dist + +makes one package for every platform (plan 4.8) from single-platform ones: every platform's +externals, each runtime in support/ (where the external looks first), each platform's +licenses in licenses/, and the rest — which must be the same in all of them — once. + Standard library only, so the runtime's own interpreter can run it. """ @@ -24,8 +32,12 @@ import argparse import json +import os import shutil +import stat import sys +import tempfile +import zipfile from dataclasses import dataclass from pathlib import Path @@ -49,6 +61,14 @@ "PRODUCTION-PLAN.md") +# Each platform's folder for its runtime in a package for every platform (plan 4.8); the external +# names its own (runtime_platform() in tap.python_tilde_package.h). +RUNTIME_PLATFORMS = ["macos-arm64", "macos-x86_64", "windows-x64"] + +# What differs between single-platform packages, and is merged rather than copied once. +PER_PLATFORM = {"externals", "support", "licenses"} + + class AssemblyError(Exception): pass @@ -214,6 +234,106 @@ def assemble(platform: str, output: Path, expected_version: str | None) -> Path: return package +def same_content(a: Path, b: Path) -> bool: + """Whether two files or folders hold the same files with the same contents, line endings aside + (a Windows checkout has CRLF where a Mac's has LF).""" + if a.is_file() or b.is_file(): + return a.is_file() and b.is_file() and \ + a.read_bytes().replace(b"\r\n", b"\n") == b.read_bytes().replace(b"\r\n", b"\n") + files_a = sorted(p.relative_to(a) for p in a.rglob("*") if p.is_file()) + files_b = sorted(p.relative_to(b) for p in b.rglob("*") if p.is_file()) + return files_a == files_b and all(same_content(a / f, b / f) for f in files_a) + + +def extract(archive: Path, destination: Path) -> None: + """Unzip a single-platform release zip as the platform that made it would: entries named with + backslashes (as some Windows zip writers make them) as folders, and the macOS runtime's symlinks + and executable bits as they were — which Python's zipfile leaves out.""" + with zipfile.ZipFile(archive) as zip_file: + for info in zip_file.infolist(): + name = info.filename.replace("\\", "/") + if name.startswith("__MACOSX/") or ".." in Path(name).parts: + continue # resource forks; and never a path out of the destination + target = destination / name + mode = info.external_attr >> 16 if info.create_system == 3 else 0 # Unix + if name.endswith("/"): + target.mkdir(parents=True, exist_ok=True) + elif stat.S_ISLNK(mode): + target.parent.mkdir(parents=True, exist_ok=True) + os.symlink(zip_file.read(info).decode("utf-8"), target) + else: + target.parent.mkdir(parents=True, exist_ok=True) + target.write_bytes(zip_file.read(info)) + if mode & 0o777: + target.chmod(mode & 0o777) + + +def merge(packages: dict[str, Path], output: Path) -> Path: + """One package for every platform (plan 4.8) from single-platform ones, each a PythonTap/ folder + or a release zip holding one, keyed by its runtime platform.""" + with tempfile.TemporaryDirectory() as unpacked: + folders: dict[str, Path] = {} + for platform, source in packages.items(): + if source.suffix == ".zip": + extract(source, Path(unpacked) / platform) + source = Path(unpacked) / platform / PACKAGE_NAME + folders[platform] = source + return merge_folders(folders, output) + + +def merge_folders(packages: dict[str, Path], output: Path) -> Path: + unknown = sorted(set(packages) - set(RUNTIME_PLATFORMS)) + if unknown: + raise AssemblyError(f"unknown platform(s) {', '.join(unknown)}; expected {', '.join(RUNTIME_PLATFORMS)}") + for platform, source in packages.items(): + if not (source / "support").is_dir() or not (source / "externals").is_dir(): + raise AssemblyError(f"{source} is not a single-platform package (no support/ or externals/)") + # the shared content comes from a Mac package where there is one: its text has LF line endings + order = sorted(packages, key=lambda platform: not platform.startswith("macos")) + base = packages[order[0]] + + package = output / PACKAGE_NAME + if package.exists(): + shutil.rmtree(package) + package.mkdir(parents=True) + + for entry in sorted(base.iterdir()): + if entry.name in PER_PLATFORM: + continue + for platform in order[1:]: + if not same_content(entry, packages[platform] / entry.name): + raise AssemblyError(f"{entry.name} differs between the {order[0]} and {platform} packages") + if entry.is_dir(): + shutil.copytree(entry, package / entry.name, symlinks=True) + else: + shutil.copy2(entry, package / entry.name) + + (package / "externals").mkdir() + for platform in order: + for external in sorted((packages[platform] / "externals").iterdir()): + destination = package / "externals" / external.name + if destination.exists(): + continue # the same universal macOS external, built on each Mac's runner: one is enough + if external.is_dir(): + shutil.copytree(external, destination, symlinks=True) + else: + shutil.copy2(external, destination) + + lines = ["# Third-party licenses", "", + "This package carries a runtime for each platform, so each platform's licenses are", + "collected separately — what ships for it:", ""] + for platform in RUNTIME_PLATFORMS: + if platform not in packages: + continue + shutil.copytree(packages[platform] / "support", package / "support" / platform, symlinks=True) + shutil.copytree(packages[platform] / "licenses", package / "licenses" / platform) + lines.append(f"- [{platform}]({platform}/README.md)") + (package / "licenses" / "README.md").write_text("\n".join(lines) + "\n", encoding="utf-8") + + print(f"merged {package} ({', '.join(p for p in RUNTIME_PLATFORMS if p in packages)})") + return package + + def main() -> int: parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0]) parser.add_argument("--platform", choices=sorted(EXTERNALS), help="the platform whose externals to package") @@ -222,10 +342,21 @@ def main() -> int: parser.add_argument("--licenses-only", action="store_true", help="only collect the licenses") parser.add_argument("--support", type=Path, default=PACKAGE_ROOT / "support", help="the runtime to collect licenses from (with --licenses-only)") + parser.add_argument("--merge", nargs="+", metavar="PLATFORM=PATH", + help="merge single-platform packages (PythonTap/ folders or release zips) into one " + f"for every platform (platforms: {', '.join(RUNTIME_PLATFORMS)})") args = parser.parse_args() try: - if args.licenses_only: + if args.merge: + packages: dict[str, Path] = {} + for item in args.merge: + platform, _, path = item.partition("=") + if not path: + parser.error(f"--merge takes PLATFORM=PATH, not {item!r}") + packages[platform] = Path(path) + merge(packages, args.output) + elif args.licenses_only: licenses = collect_licenses(args.support, args.output / "licenses") print(f"collected {len(licenses)} license files into {args.output / 'licenses'}") else: diff --git a/source/projects/tap.python_tilde/CMakeLists.txt b/source/projects/tap.python_tilde/CMakeLists.txt index b35e712..0c73129 100644 --- a/source/projects/tap.python_tilde/CMakeLists.txt +++ b/source/projects/tap.python_tilde/CMakeLists.txt @@ -102,6 +102,18 @@ else () endif () if (APPLE) + # In a package that carries every platform's runtime (plan 4.8), each architecture's is in + # support/macos-: give each slice of the universal binary an rpath to its own, ahead of + # support/lib, where a single-platform package or a checkout has it. (SHELL: keeps CMake from + # merging the repeated -Xarch_ flags.) + set(_rpath_archs "${CMAKE_OSX_ARCHITECTURES}") + if (NOT _rpath_archs) + set(_rpath_archs "${CMAKE_HOST_SYSTEM_PROCESSOR}") + endif () + foreach (_arch IN LISTS _rpath_archs) + target_link_options(${PROJECT_NAME} PRIVATE + "SHELL:-Xarch_${_arch} -Wl,-rpath,@loader_path/../../../../support/macos-${_arch}/lib") + endforeach () target_link_options(${PROJECT_NAME} PRIVATE "-Wl,-rpath,@loader_path/../../../../support/lib") # Only that relative rpath: without this CMake also embeds the absolute path of # the build machine's support/lib, which would leak into every shipped binary. diff --git a/source/projects/tap.python_tilde/tap.python_tilde.h b/source/projects/tap.python_tilde/tap.python_tilde.h index fd6f8d5..d7c413a 100644 --- a/source/projects/tap.python_tilde/tap.python_tilde.h +++ b/source/projects/tap.python_tilde/tap.python_tilde.h @@ -172,7 +172,7 @@ class python : public object, public vector_operator<> { // (see this object's CMakeLists.txt) const std::filesystem::path home{TAP_PYTHON_HOME}; #else - const auto home = package / "support"; + const auto home = runtime::runtime_home(package); // support/, or support/ (plan 4.8) #endif if (!std::filesystem::exists(home)) { diff --git a/source/projects/tap.python_tilde/tap.python_tilde_package.h b/source/projects/tap.python_tilde/tap.python_tilde_package.h index 2e47444..73bfcfc 100644 --- a/source/projects/tap.python_tilde/tap.python_tilde_package.h +++ b/source/projects/tap.python_tilde/tap.python_tilde_package.h @@ -61,6 +61,29 @@ namespace tap::python { #endif } + /// This build's folder name for its runtime in a package that carries every platform's (plan + /// 4.8): support/macos-arm64, support/macos-x86_64 or support/windows-x64. Each slice of the + /// universal macOS external names its own architecture. + inline const char* runtime_platform() { +#if defined(WIN_VERSION) + return "windows-x64"; +#elif defined(__aarch64__) || defined(__arm64__) + return "macos-arm64"; +#else + return "macos-x86_64"; +#endif + } + + /// The runtime this external uses: /support/ in a package that carries every + /// platform's runtime (plan 4.8), or /support in one made for a single platform — a + /// per-platform release, or a checkout with scripts/install-runtime.* run in it. + inline std::filesystem::path runtime_home(const std::filesystem::path& package) { + const auto support = package / "support"; + const auto own = support / runtime_platform(); + std::error_code ec; + return std::filesystem::is_directory(own, ec) ? own : support; + } + /// Whether the CPython library the external was built against can be used, asked before the /// first Python call. The external links it weakly on macOS and delay-loads it on Windows (see /// this object's CMakeLists.txt), so that it loads without a runtime and can say what is diff --git a/source/projects/tap.python_tilde/tap.python_tilde_test.cpp b/source/projects/tap.python_tilde/tap.python_tilde_test.cpp index 9321a78..e93b800 100644 --- a/source/projects/tap.python_tilde/tap.python_tilde_test.cpp +++ b/source/projects/tap.python_tilde/tap.python_tilde_test.cpp @@ -456,3 +456,26 @@ SCENARIO("With @mode worker, process() runs on a thread of its own, @latency mil } } } + +SCENARIO("The runtime is support/ in a package that carries every platform's, else support/ (plan 4.8)") { + const auto package = std::filesystem::temp_directory_path() / "tap-python-runtime-home-test"; + std::filesystem::remove_all(package); + std::filesystem::create_directories(package / "support"); + + THEN("a single-platform package's runtime is support/") { + CHECK(runtime::runtime_home(package) == package / "support"); + } + WHEN("support/ holds a folder for this platform") { + std::filesystem::create_directories(package / "support" / runtime::runtime_platform()); + THEN("that is the runtime") { + CHECK(runtime::runtime_home(package) == package / "support" / runtime::runtime_platform()); + } + } + WHEN("support/ holds only other platforms' folders") { + std::filesystem::create_directories(package / "support" / "another-platform"); + THEN("the runtime is still support/") { + CHECK(runtime::runtime_home(package) == package / "support"); + } + } + std::filesystem::remove_all(package); +}