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.
auto session = ;
// From a UI timer, on your own thread:
for
for
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.