How mariomatheuspombal/actix-glpc works
Project type and purpose
• This is an open-source Rust library suite implementing an actor-model framework (“actix”), a set of procedural macros to simplify message definitions (“actix-derive”), and a publish/subscribe broker extension (“actix-broker”).
• The primary goal is to provide a highly concurrent, asynchronous runtime for actors, plus utility crates for automating boilerplate and enabling pub/sub within that runtime.
File structure
• Top‐level crates:
• actix/ → core runtime (actors, contexts, mailboxes, scheduler, futures integration).
• actix-derive/ → proc-macro definitions (Message, MessageResponse, runtime entrypoint annotations).
• actix-broker/ → actor-based pub/sub broker, example brokers and client APIs.
• Shared configuration files at root (Cargo.toml, CI workflows, formatting rules) orchestrate testing and publication of all crates.
• Examples and tests in each crate demonstrate usage patterns and integration points.
README for additional insights
• The actix README describes:
• the actor lifecycle (create, start, stop),
• message dispatch and handler resolution,
• integration points (Tokio, futures),
• high-level design goals (performance, scalability).
• actix-derive README explains the proc-macro expansion hooks.
• actix-broker README outlines the pub/sub API.
a. Main components
1. Actix Core Runtime
• System Arbiter / Thread Pool
• Actor instances & Context
• Mailbox & Envelope
• Registry (actor lookup by name/address)
• Integration with Tokio reactor/futures
2. Derive Macros
• Compile-time macros that generate handler glue code
• Message trait implementations
3. Pub/Sub Broker
• Broker actor (internal registry of subscribers)
• Publisher API
• Subscriber API
4. External Adapters (e.g., actix-web, custom actors)
b. Relationships & interactions
• At compile time: actix-derive → injects code into actor/message definitions that target the Actix Core Runtime.
• At runtime: User code spins up a System Arbiter → spawns Actors → each has a Context that holds a Mailbox.
• Messages flow: Sender → Envelope → Mailbox → Actor’s Handler → optional MessageResponse → back to sender.
• Broker: acts as an Actor registered in the Registry → publishers send “Publish(topic, payload)” → broker fans out to subscriber mailboxes.
• Derive macros eliminate manual impl of Message/Handler; they generate code that hooks into the Actor dispatch loop.
c. Architectural patterns & design principles
• Actor Model: isolation, message passing, supervision.
• Dependency inversion: core runtime unaware of user-defined actors.
• Code generation (compile-time) to reduce boilerplate.
• Modular crate layout: core runtime, macros, and optional broker.
d. Key technologies & libraries
• Rust async/futures & Tokio under the hood for scheduling.
• syn/quote in actix-derive for proc-macros.
• Standard Rust channels or internal queues for mailboxes.
Detail
• Essential elements without over-fragmenting: group low-level futures integration under “async runtime” rather than every internal future combinator.