How tigrux/traeger works
Project type and purpose
• Traeger is a modular C++ library (with Go and Python bindings) that implements the Actor Model, value‑semantics, serialization, and network messaging patterns.
• It is not a standalone application but a library suite meant to be embedded in client code (examples in C++, Go, Python).
File structure
• Top‑level CMake scripts and Dockerfiles: orchestrate building the core C++ libraries, Go bindings, Python bindings, and examples.
• traeger/actor, traeger/format, traeger/socket, traeger/value: the four core modules of the library.
• python/ and go/: FFI layers exposing the core modules to Python (via Nanobind/CMake) and Go.
• examples/: sample client applications demonstrating usage patterns (value semantics, actors, serialization, socket patterns).
• traeger/tests: unit tests for each core module.
README insights
• Core modules correspond precisely to the Actor Model abstractions, serialization formats (JSON/YAML/MsgPack), ZeroMQ socket patterns (REQ/REP, PUB/SUB), and value‑types.
• External dependencies (immer, nlohmann/json, yaml‑cpp, msgpack‑c, ZeroMQ, nanobind) are statically fetched by CMake and link into the core libraries.
Main components
a. Core C++ Libraries:
• Actor module (Scheduler, Mailbox, Actor definitions, Promise/Result)
• Value module (Value, List, Map, Variant)
• Format module (Format interface, JSON/YAML/MsgPack adapters)
• Socket module (Context, Publisher, Subscriber, Requester, Replier)
b. FFI Bindings:
• Go bindings (go/traeger_*.go)
• Python bindings (python/traeger_python.cpp/hpp using Nanobind)
c. External Dependencies:
• ZeroMQ (network transport)
• nlohmann/json, yaml‑cpp, msgpack‑c (serialization)
• immer (persistent data structures)
• nanobind (Python binding)
d. Client Applications:
• C++ examples (in examples/)
• Go examples (examples/go/)
• Python examples (examples/python/)
Relationships and interactions
• Actor module uses Value types to carry message payloads.
• Socket module invokes the Format module to encode/decode Values over the network, then forwards requests to an Actor’s Mailbox.
• Scheduler (in Actor module) manages thread pools for concurrent execution of messages.
• FFI layers wrap the core modules, exposing the same abstractions in Go or Python.
• External dependencies feed into core modules at build time (e.g., Format → json/yaml/msgpack libraries; Socket → ZeroMQ).
Architectural patterns/design principles
• Layered architecture: Core modules at the center, FFI bindings around them, client apps at the outer layer.
• Modular design: Each module has its own directory, CMakeLists, tests.
• Dependency inversion: Core modules depend only on minimal standard C++ and abstract interfaces; concrete serializers/sockets are plugged in.
• Actor Model: mailboxes, promises, scheduler.
• Zero‑MQ messaging patterns: REQ/REP, PUB/SUB.
Essential elements without over‑splitting
• four core modules, FFI layers, external dependencies, and client apps.
• That all important interactions and dependencies are visible.