c-api-extend

Imported from yvanvds/yse-soundengine (.claude/skills/c-api-extend/SKILL.md). Install upstream with npx skills add yvanvds/yse-soundengine --skill c-api-extend. Copyright stays with the author.

Extending the YSE C API for new engine surface

YseEngine/c_api/ is the only entry point for FFI consumers (Dart, Python, …). The C API has explicit rules — RT-safe callback bridges, opaque-handle ownership, null-safe no-op semantics, YSE_C_CALLBACK ABI defence, exception-to-YseStatus translation, enum drift guard — that the engine's own public C++ API does not enforce. New wrapping must follow all of them; a careless callback bridge can stall the audio thread.

This skill governs how to wrap new engine surface in the C API. Read it fully before editing any file under YseEngine/c_api/.

Issue tracking — GitHub Issues first

CLAUDE.md mandates an issue before code. For this skill:

• File the issue first with gh issue create --title "c-api: ...". Use the enhancement or task template; tag the layer as c-api.
• Branch from dev as <issue-number>-c-api-<short-slug> and PR back to dev. Not master — see CLAUDE.md §1.
• Read context with gh issue view <n> before starting if the request mentions an existing issue number.

The gh CLI is authenticated in the project environment.

When to invoke this skill

Yes:

• A new engine class / method / enum was added and needs C-ABI exposure.
• The user asks to audit the C API for drift from the engine.
• The user is starting a new C-API wrapping pass (e.g. a sub-issue of a C API audit epic such as #898).

No:

• Modifying behaviour of an existing C-API function without adding surface — that's a regular fix, use the normal workflow.
• Internal engine refactors that don't change the public C++ surface.
• Adding audio-thread-reachable callbacks (dspSourceObject user callback, customFileReader) on a casual wrapping pass. Those need design work — see the "Callback bridge rules" block in yse_c_internal.hpp.

The six conventions

Every new C-API entry point must respect all six.

1. Opaque handle shape and ownership

Each engine type that gets a C handle is declared with typedef struct YseFoo YseFoo; and accessed only via YseFoo* pointers. The .cpp file does reinterpret_cast<YSE::foo*>(handle). Never expose any C++ type, class, namespace, reference, or template across the C ABI.

Every typedef in its home header carries a one-line ownership comment:

/* Owned — release with yse_foo_destroy. */
typedef struct YseFoo YseFoo;

/* Borrowed singleton — owned by the engine, never destroy.
   Obtain via yse_foo_get(). */
typedef struct YseFoo YseFoo;

/* Borrowed — owned by parent YsePatcher. Release with
   yse_patcher_delete_object(patcher, handle); never call a destroy on
   the handle directly. */
typedef struct YsePHandle YsePHandle;

Dual-shape types (e.g. YseChannel is owned via yse_channel_create but borrowed via the pre-built accessors) get both lines.

Forward-declaration typedefs (in headers that don't own the type) point the reader at the home header rather than duplicating the ownership note:

/* Forward declarations — see yse_channel.h / yse_dsp.h for ownership. */
typedef struct YseChannel YseChannel;
typedef struct YseDspBuffer YseDspBuffer;

Every handle typedef — home header and forward declaration alike — sits behind its own YSE_C_HANDLE_<Type> guard (#976), because repeating a typedef is a C11 feature and the headers must stay C99-clean:

#ifndef YSE_C_HANDLE_YseFoo
#define YSE_C_HANDLE_YseFoo
/** Owned — release with yse_foo_destroy. */
typedef struct YseFoo YseFoo;
#endif

Keep the comment inside the guard, directly above the typedef: placed above the #ifndef, Doxygen attaches it to the #define instead, and the Sphinx build fails on the duplicated macro.

The yse_c99_header_check object library in Tests/CMakeLists.txt compiles every public header as -std=c99 -pedantic-errors, so an unguarded typedef fails the test build.

Canonical examples: yse_patcher.h (owned + borrowed pair), yse_reverb.h (dual-shape).

2. Header layout

Every include/yse_c/yse_<module>.h:

• Top-of-file block comment naming purpose, the mirrored engine source, scope notes, and the null-safe-no-op convention statement.
• #ifndef / #define / #endif include guards. No #pragma once.
• #include "yse_common.h" (and yse_enums.h if needed) — never an engine C++ header.
• #ifdef __cplusplus / extern "C" { ... } / #endif wraps the body.
• YSE_C_API on every exported function declaration.
• YSE_C_CALLBACK on every callback typedef, named Yse<Module><What>Callback in PascalCase (YseBusTapCallback, YseScriptErrorCallback, YsePatcherSendCallback) — never a lowercase yse_*_cb (#911 renamed the last of those).
• Functions carry their header's module prefix: yse_<module>_... (yse_python_run_script, not yse_run_script).
• General-purpose helpers live in yse_common.h (yse_last_error, yse_free_string for library-allocated strings), not in whichever module first needed them.
• All booleans as int (0/1), never bool. All sizes as size_t or unsigned int. Strings as const char* (in) or char* + size_t (snprintf-style out).

Canonical example: yse_sound.h.

3. Function shape

The header-top convention paragraph captures the void-no-op rule once for the whole header. Per-function comments are reserved for genuinely surprising behaviour.

Body pattern for fallible operations (lift from yse_sound.cpp):

YSE_C_API YseStatus yse_x_load(YseX* h, const char* arg) {
  if (!h) return YSE_ERR_INVALID_HANDLE;
  if (!arg) return YSE_ERR_INVALID_ARGUMENT;
  try {
    if (!to_cpp(h)->load(arg)) {
      yse_c::set_last_error(std::string("x load failed for: ") + arg);
      return YSE_ERR_<specific>;
    }
    return YSE_OK;
  } catch (const std::exception& e) {
    yse_c::set_last_error(e.what());
    return YSE_ERR_EXCEPTION;
  } catch (...) {
    yse_c::set_last_error("yse_x_load: unknown C++ exception");
    return YSE_ERR_EXCEPTION;
  }
}

Body pattern for void state-change:

YSE_C_API void yse_x_play(YseX* h) { if (h) to_cpp(h)->play(); }

Body pattern for string-out:

YSE_C_API size_t yse_x_get_name(YseX* h, char* buf, size_t cap) {
  if (!h) { if (buf && cap > 0) buf[0] = '\0'; return 0; }
  return copy_string(to_cpp(h)->getName(), buf, cap);
}

Canonical example for the snprintf pattern: yse_device.cpp.

4. Callback bridges — RT-safe shape

When the engine invokes a user-provided callback on a non-host thread (audio callback, RtMidi input thread, file streaming worker, the control-thread occlusion driver, future dspSourceObject / customFileReader paths), the bridge:

1. Holds the callback + user_data as one immutable pair node behind a single std::atomic<Pair*> — never two separate atomics, which let a dispatch between the two stores of a re-install pair one install's cb with another's user_data (#902, #916). Never std::mutex or std::lock_guard on the dispatch path.
2. Installs by allocating the new pair (inside the ABI exception barrier) and publishing it with one atomic exchange.
3. Dispatches by loading the pointer once (return if null) and reading cb and user_data from that same node. The replaced node is freed only after a named grace period proves no dispatch still reads it: the log bridge waits for the sink mutex every dispatch runs under; the MIDI raw bridge uses a seq_cst reader-count handshake around the pointer load, with no user code inside the window the installer waits on. A straight passthrough to an engine setter is fine only when that setter keeps the pair as one node itself (YSE::midiIn's raw / parsed setters do since #917); still wrap the install in the exception barrier.
4. Does not malloc / new / construct std::string on dispatch when the bridge can fire from the audio callback. For raw byte buffers needed by an async-Dart host, preallocate a per-handle pool keyed by the handle.
5. Uses YSE_C_CALLBACK on the typedef.
6. If the bridge transfers heap ownership to the host (Dart's NativeCallable.listener requires this), pair the callback with a yse_<module>_free_message function and document the contract beside the typedef.

Canonical examples:

• yse_midi.cpp — c_raw_bridge, pair-pointer swap reclaimed by a reader-count handshake; malloc per call is acceptable because the RtMidi input thread is not the audio callback.
• yse_log.cpp — CallbackBridge, same pair-pointer swap reclaimed behind the log sink mutex, same Dart-ownership malloc.

The "Callback bridge rules" block at the head of yse_c_internal.hpp restates these rules in detail. Read it before designing any new bridge.

5. Enum mirroring + drift guard

When the engine adds an enum value that should be visible from the C API:

1. Add a matching Yse<Name>_<VALUE> entry to yse_enums.h. Mirror the integer value exactly. Use C-compatible typedef enum {...} Yse<Name>; syntax (not enum class).
2. Add a YSE_ASSERT_ENUM(YSE_..., YSE::...); line to yse_enums_check.cpp. The build fails loudly if the values drift.

If the engine adds a brand-new enum, add the full mirror block + a full set of YSE_ASSERT_ENUM lines. The drift guard is the only safety net for the hand-mirrored file.

6. Build + test integration

• New .cpp file → append to YSE_C_API_SRCS in c_api/CMakeLists.txt.
• New public functions → add at least one smoke test under Tests/<module>/. The doctest harness picks up TEST_CASE without further wiring; see existing tests for patterns. Tests that need a null device use TestHelpers::engineInit().
• Build with the project wrapper, never raw cmake invocations: python yse.py build && python yse.py test. CTest must stay green across all 44 entries (count them with ctest --test-dir build-tests -N; the number grows as suites are isolated).
• C API mirror suites run per process. capilowcov, capilowcovlife, capisurface, close_interleaving, buscapi and the other C-API suites are registered as their own ctest entries and are not all exercised by the monolithic yse_unit_tests binary. When touching the registry, metadata, protocols or lifecycle, run the relevant entries individually (ctest --test-dir build-tests -R <name>), not just the monolithic binary.
• Python-gated surface (yse_python.h, yse_module) only builds its live half under python yse.py build --python / python yse.py test --python — run those when touching it.

Workflow

1. Inventory the new engine surface. Read the engine header (e.g. YseEngine/sound/soundInterface.hpp); list every public method, enum, and callback. Skip private helpers and the implementation pimpls.
2. Map ownership. For each new class, decide: owned (user create/destroy), borrowed singleton, or borrowed by parent.
3. Plan the module file. New subsystem → new yse_<module>.h + yse_<module>.cpp pair + CMakeLists entry. Extending an existing subsystem → add to the existing pair.
4. Apply the six conventions as you write. Lift bodies from the canonical examples — don't re-invent the shape.
5. Update the enum mirror + drift guard if any new enum value landed in the engine.
6. Update c_api/CMakeLists.txt if new files were added.
7. Add a test stub under Tests/<module>/. At minimum: a TEST_CASE that exercises create/destroy and one method.
8. Build + test: python yse.py build && python yse.py test. Must be green.
9. PR to dev with a body that references the closing issue and lists every new public function in the summary.

Hard refusals

Stop and surface a design note rather than emit code that:

• Contains std::mutex or std::lock_guard in any callback bridge body. (PR #63 had to remove these from yse_log.cpp; do not put them back.) The rule is about bridge dispatch paths and anything the audio thread can reach. The one allowed exception today is the live-handle registry in yse_instrument.cpp (registryMutex()): SFZ-instrument / DX7-bank handles are validated against it to turn double-free and use-after-destroy into logged no-ops (#178), and every caller is a control / setup-thread entry point that already allocates and reads files. Nothing on the audio thread or in a callback touches it. A new mutex needs the same argument, written beside it in a comment, or it is refused.
• Allocates memory (malloc, new, std::string construction) in a callback that fires on the audio thread. If the host genuinely needs byte ownership, design a preallocated pool.
• Exposes any C++ type, namespace, reference, or template in a public yse_c/*.h header.
• Catches std::exception and rethrows, swallows, or returns 0/NULL without first calling yse_c::set_last_error.
• Adds a void function that throws on null instead of being a null-safe no-op.
• Adds a callback typedef without YSE_C_CALLBACK.
• Adds an enum to yse_enums.h without a matching YSE_ASSERT_ENUM in yse_enums_check.cpp.

If the engine's design genuinely requires one of these (rare), file an issue describing the conflict and wait for a decision before proceeding.

Things this skill DOES NOT do

• Modify vendored dependencies under dependencies/ or build*/_deps/.
• Add new public methods, classes, or enums to the engine. Engine changes go through the engine's own workflow first; this skill mirrors them.
• Refactor existing C-API surface unless the engine change requires it.
• Wrap callbacks that fire on the audio thread (dspSourceObject, customFileReader) — those need additional design work (preallocated pools, stack-only return paths) per yse_c_internal.hpp's rules block. Surface a design proposal first. (Occlusion is no longer deferred: since #209 it runs on the control thread inside System().update(), and #906 bridged it as yse_system_set_occlusion_callback in yse_system.cpp.)
• Modify CLAUDE.md or PROJECT_OVERVIEW.md unless the wrapping pass introduces a structural change worth documenting at the project root.

Verification

Before reporting the wrapping task complete:

• python yse.py build succeeds with no new warnings.
• python yse.py test passes all 44 CTest entries (the project's full suite, not just the new test), plus the per-process C-API entries you touched run individually.
• grep "std::mutex\|std::lock_guard" YseEngine/c_api/ returns nothing beyond the documented yse_instrument.cpp handle-registry exception (see Hard refusals).
• Every new public function in include/yse_c/*.h is either covered by the header-top void-no-op convention or carries its own explanatory comment.
• Every new opaque typedef has the ownership one-liner.
• Every new callback typedef has YSE_C_CALLBACK.
• Every new enum value has a matching YSE_ASSERT_ENUM line.

If any of these fail, the wrapping is incomplete — keep iterating rather than reporting done.