How eclipse-score/inc_feo works
Project Type and Purpose
• This is a Rust‐centric, multi‐crate, Bazel/Cargo‐driven instrumentation and tracing library (“score‐feo”).
• It provides a core runtime (the feo crate) for event‐based Agents (primary/secondary/recorder), pluggable signalling layers (direct vs. relayed), recording backends, logging, time utilities, and integrations (Perfetto, external C++ libs).
• It also includes example applications (cycle‐benchmark, mini‐adas), a log‐demon (logd), and model crates (perfetto-model).
File Structure
• Top‐level build orchestrators:
• Bazel files: BUILD.bazel, MODULE.bazel, .github/workflows/ci.yml
• Docker: docker/
• Tools: tools/format
• Workspace crates (each under its own folder, each with BUILD.bazel and Cargo.toml):
• Core runtime: feo/
• Communication support: feo-com/
• C++ build macros: feo-cpp-build/, feo-cpp-macros/
• Logging: feo-log/, feo-logger/
• Timing: feo-time/
• Tracing frontends: feo-tracer/, feo-tracing/
• CLI server: logd/
• Protocol model: perfetto-model/
• Examples: examples/rust/... with Rust apps that link into the feo ecosystem.
• FFI/C++ integrations under mini-adas/src/cpp & headers.
Extract Insights from README
• Build/test with Bazel or Cargo.
• Examples demonstrate runtime usage (bazel run //examples/rust/mini-adas:adas_primary).
• Profiling using samply and bytehound points to performance‐sensitive design.
Components & Interactions
a. Main Components
1. Build System Layer
• Bazel (CI pipeline, workspace orchestration)
• Cargo (example builds)
2. Libraries Layer
• Core feo crate: defines Agent interfaces, scheduler, signalling abstractions, recording registry.
• feo-com: IPC channels (shmem, iox2).
• feo-logger / feo-log: Logging APIs and backends.
• feo-time: Timestamp and clock utilities.
• feo-tracer / feo-tracing: Tracing instrumentation and protocol support.
• perfetto-model: Protobuf definitions for Perfetto.
• feo-cpp-build / feo-cpp-macros: Facilitate C++ FFI.
3. Runtime Agents & Processes
• Primary agent (event producer)
• Recorder agent (aggregator/writer)
• Secondary agent (consumer/merger)
4. Signalling & Communication
• Direct in‐process (mpsc channels)
• Relayed across sockets or shared memory
5. Storage & Export
• In‐memory registry → disk via recorders
• logd daemon: RPC interface for client streams or packets
• Perfetto exporter (via perfetto-model)
6. Example Applications
• Rust cycle‐benchmark, mini‐adas (with C++ FFI)
• Linking paths into core crates
7. External Tools & Services
• Docker environment (for containerized runs)
• Profilers: samply, bytehound
• Browsers / Perfetto UI
b. Relationships and Data Flows
• Agents emit events → pass through Signalling layer → arrive at Recorder → persist or forward.
• logd connects to built‐in IPC exports or socket endpoints to receive/serve logs.
• FFI layer bridges Rust APIs to C++ components (lane_assist.cpp, trajec_vis.cpp) in mini‐adas.
c. Architectural Patterns & Principles
• Modular monorepo: each feature in its own crate
• Layered design:
• Interface (Agent, topicspec)
• Signalling (common, direct, relayed)
• Recording (registry, transcoder)
• Export (logd, perfetto)
• Pluggable backends (mpsc vs. shared memory vs. sockets)
• Zero‐cost abstractions in Rust (traits + generics)
• FFI isolation via dedicated crates
d. Key Technologies / Frameworks
• Rust toolchain (Cargo, clippy)
• Bazel + Bazelisk for large‐scale workspace management
• Tokio / async (implicit in signalling modules)
• Protobuf (perfetto‐model)
• C/C++ FFI via bindgen/ffi.rs
• IPC: Linux shared memory, iox2, UNIX sockets, mpsc channels
• Build dependencies (Bazel/Cargo → crates)
• Runtime data flow (Agent → Signalling → Recorder → logd/Perfetto)
Capturing Essential Elements
• Crates as modular components, grouped by functionality.
• Multi‐process topology (primary, secondary, recorder agents).
• External profiling and export services as side components.
• Don’t overcrowd: cluster similar crates (e.g., feo-log + feo-logger) but keep them distinct.