Crate epics_libcom_rs

Expand description

EPICS libCom for Rust: the layer an IOC is built on, with no record system above it.

This is epics_base_rs::runtime and epics_base_rs::net lifted out of epics-base-rs (issue #55) so a consumer — a protocol client, a gateway, pvxs-rs — can take the concurrency and socket primitives without taking the database with them. The name is C’s: libCom is where upstream EPICS keeps epicsThread, epicsTime, errlog, envDefs and osiSock, which is exactly this crate’s two modules.

epics-base-rs re-exports both modules at their original paths, so epics_base_rs::runtime::… and epics_base_rs::net::… still resolve and nothing downstream had to change.

runtime — the task seam and its two backends, epicsThread-parity priority bands, errlog, the EPICS string/environment types, the general-time provider.
net — the EPICS protocols’ shared socket layer: per-NIC async UDP, interface enumeration, loopback multicast. Host-only; the wire constants beside it compile for every target, RTEMS included.
walltime — WallTime, the wall-clock instant runtime::time returns. It lived in epics_base_rs::types and moved down with its producer; epics-base-rs re-exports it at types::WallTime.

§Features

The task backend is not one: it is chosen by the EPICS_RS_BUILD_EXEC_BACKEND environment variable, read by build.rs. See EXEC_BACKEND.

linux-rt — back runtime::sync::PriorityInheritanceMutex with a PTHREAD_PRIO_INHERIT pthread_mutex_t on Linux.

§C reference pins

Every file.c:NNN citation in this crate resolves at the tree and revision below, not at whatever that tree’s working copy holds today. These trees are checked out on local branches here and run ahead of their pins.

tree	pinned revision
`epics-base`	`R7.0.10`
`pvxs`	`1.5.1-42-gb568e93`
`ca-gateway`	`R2-1-3-0-54-g0666f21`
`asyn`	`R4-45-19-ge2a281e2`
`calc`	`R3-7-5-49-gf207871`

Resolve by symbol at the pin; the line is a hint. Find the named function, struct, macro or field first, and treat the line number as a hint that has to land inside that construct. Three cases follow:

Construct at the pin, line lands in it — the citation is exact. A reference checkout ahead of the pin will disagree; that disagreement is the checkout’s, not the citation’s.
Construct at the pin, line lands outside it — line drift. Keep the symbol and move the line to the pin’s.
Construct absent at the pin — the citation means code added after it, and is NOT moved onto the pin, where it would point at lines that do not exist. It names the revision it means inline, beside the line span: the upstream PR and commit, and that both are later than the pin this table gives. epics-libcom-rs already carries that form.

Every pin above passes git merge-base --is-ancestor <pin> origin/<default> in its own tree, which is the test a pin has to meet. A git describe string names an exact commit and is worth as much as a tag; what disqualifies a revision is being reachable only from a fork branch or an unmerged PR, because then it names nothing a reader outside this workspace can fetch.

Resolve each citation on its own. One sentence can cite two lines that are right at different revisions, and a check run at either revision then reports a single tidy error while vouching for the very citation the other condemns.

A row reading no settled pin means no revision has been agreed for that tree: say which revision you read, and do not take its HEAD for the pin. Citations into non-EPICS sources (libc, RTEMS, rtems-libbsd, VxWorks, vendored third-party) are outside this table and carry no pin.

Modules§

net: Cross-platform networking primitives shared by epics-ca-rs, epics-pva-rs, and epics-bridge-rs.
runtime: The concurrency, timing, logging and OS-facing primitives an IOC is built on — C libCom’s epicsThread / epicsTime / errlog / envDefs half.
walltime: WallTime — a wall-clock instant with full EPICS nanosecond precision on every platform.

Macros§

rt_debug: Debug-level runtime log line. Routes through the tracing facade.
rt_error: Error-level runtime log line. Routes through the tracing facade.
rt_info: Info-level runtime log line. Routes through the tracing facade.
rt_warn: Warn-level runtime log line. Routes through the tracing facade.

Constants§

EXEC_BACKEND: Which runtime::task backend this build selected — true for the reactor-free std-thread runtime::background executor, false for tokio.