prolink-cxx 0.3.0

A C++ binding for prolink, generated by cxx
Documentation

prolink-cxx

A C++ binding for prolink, generated by cxx.

Built for Mixxx, whose Pro DJ Link support is being replaced by calls into this library. The host is meant to be a thin shell that renders, so everything here hands over state that is ready to display rather than parts a caller has to reassemble: no packet, no socket and no parsing in the API.

#include "prolink-cxx/src/lib.rs.h"

auto session = prolink::open(prolink::default_config());

// From a UI timer, on your own thread:
for (const prolink::Event& event : session->drain_events()) {
    if (event.kind == prolink::EventKind::Beat) { /* ... */ }
}

for (const prolink::Player& player : session->players()) {
    if (player.is_master) {
        meter->setPhase(player.bar_phase);
    }
}

Session is a real C++ class held in a rust::Box, strings arrive as rust::String, and lists as rust::Vec<T> you can range-for over. Nothing on the C++ side is unsafe, and nothing it receives needs freeing.

Why cxx rather than a C ABI

A hand-written C header has to be kept in step with the Rust by hand, and when it is not the failure is a caller's stack corrupted at run time, on a machine the author does not have. cxx generates both sides from src/lib.rs, so the same mistake is a compile error in both languages. It also carries the doc comments into the generated header, so the C++ declarations explain themselves.

The earlier C ABI in this repository was replaced by this. Its hand-written header and the layout tests that policed it existed only to solve a problem cxx does not have.

Two rules the surface follows

Events are drained, never pushed. A callback would be invoked from a tokio worker thread, which for a Qt host means every handler has to be thread-safe and re-entrant, and a slow one stalls the network. drain_events() returns everything queued since the last call, on the caller's own thread. Back-pressure is bounded rather than unbounded: Event::dropped reports what was discarded, and non-zero means the running picture is stale and the tables should be re-read.

Absent numbers are negative, never zero. A host drawing a tempo has to tell "not playing" from "0.00 BPM", and zero cannot. cxx has no Option in a shared struct, so the convention is explicit: -1.0 means "no value".

What it covers

Parity with the C++ it replaces, plus what hardware testing has since added.

Interfaces, session lifecycle, device table interfaces(), open(), devices()
Live player state players() — tempo, pitch, beat and bar phase, master, sync, handoff target, play state, loaded track
Events drain_events()
Slot contents per player media()
Browse root_menu(), track_rows(), search(), metadata()
Artwork fetch_artwork()
File and database transfer, with progress fetch_file(), fetch_database()
Serving local media serve(), Server::status(), Server::stop()
Served slots and consumers ServeStatus::media, ServeStatus::consumers
Status line is_listening(), last_error(), refresh()
Stable identity device_number_of(mac)

Two call styles, and the split is deliberate. A browse is request/response and small — a menu is a few hundred rows in one round trip — so those block and return the rows, which is what a host wants and what Mixxx's network thread is already for. A file transfer is megabytes and seconds long, so it returns a transfer id immediately and reports progress as events.

Transfers queue and retry. One at a time, because two pulls from the same deck contend for its filehandle table — and a deck answers NFSERR_STALE to everything once that table churns (F28), which the transfer path recovers from by re-mounting once. Both behaviours match the C++ this replaces; neither is visible in the function list, which is why they are called out here.

Hold the MAC, not the number. A player's number can be reassigned; its MAC cannot. device_number_of(mac) resolves late, so a request that outlives the device it named fails cleanly rather than reaching a different deck.

Browsing claims a device number in 1–4, because a deck validates the requester's number in every dbserver request and one outside that range is never offered as a source (F45). That contends with the decks for a number, so it happens on the first browse rather than at open().

Building

cargo build produces libprolink_cxx.a and generates target/cxxbridge/prolink-cxx/src/lib.rs.h. From CMake, either invoke Cargo and link the archive, or use corrosion, which does both and puts the generated header on the include path.

Unsafe

This is the only crate in the workspace that does not inherit the workspace lints, which forbid unsafe_code. The cxx::bridge macro expands to the extern declarations that make the two languages agree, and those cannot be written safely — so this crate denies it instead, and the bridge module is the single exemption. Nothing hand-written here is unsafe, which is the whole reason for choosing cxx.