### Configure Coverage Tools Source: https://github.com/slawlor/ractor/blob/main/xtask/README.md Install the required LLVM tools and the grcov utility to enable coverage reporting. ```shell rustup component add llvm-tools-preview cargo install grcov ``` -------------------------------- ### Build and Serve Ractor Unit Tests Source: https://github.com/slawlor/ractor/blob/main/unit-tests-for-wasm32-unknown-unknown.md Builds the unit tests for the Ractor project and starts a local web server to run them in a browser. Ensure you are in the Ractor project directory. ```sh wasm-pack test --firefox ./ractor ``` -------------------------------- ### Install Ractor Test Dependencies Source: https://github.com/slawlor/ractor/blob/main/unit-tests-for-wasm32-unknown-unknown.md Installs the wasm32-unknown-unknown target and the wasm-pack tool, which is used for bundling and executing Wasm tests. ```sh rustup target add wasm32-unknown-unknown cargo install wasm-pack ``` -------------------------------- ### Generate Flamegraphs for Benchmarks Source: https://github.com/slawlor/ractor/blob/main/docs/advanced_benchmarks.md Create flamegraphs for benchmark execution using the 'cargo-flamegraph' tool to visualize performance hotspots. This example targets the 'small_messages' benchmark. ```bash cargo flamegraph --bench simple_advanced_benchmarks -- --bench small_messages ``` -------------------------------- ### Ping-Pong Actor Example Source: https://github.com/slawlor/ractor/blob/main/README.md A basic actor that repeatedly sends 'ping' and 'pong' messages to itself until a counter reaches 10, then stops. It requires the `async_trait` and `ractor` crates. ```rust use ractor::{async_trait, cast, Actor, ActorProcessingErr, ActorRef}; /// [PingPong] is a basic actor that will print /// ping..pong.. repeatedly until some exit /// condition is met (a counter hits 10). Then /// it will exit pub struct PingPong; /// This is the types of message [PingPong] supports #[derive(Debug, Clone)] pub enum Message { Ping, Pong, } impl Message { // retrieve the next message in the sequence fn next(&self) -> Self { match self { Self::Ping => Self::Pong, Self::Pong => Self::Ping, } } // print out this message fn print(&self) { match self { Self::Ping => print!("ping.."), Self::Pong => print!("pong.."), } } } #[async_trait] // the implementation of our actor's "logic" impl Actor for PingPong { // An actor has a message type type Msg = Message; // and (optionally) internal state type State = u8; // Startup initialization args type Arguments = (); // Initially we need to create our state, and potentially // start some internal processing (by posting a message for // example) async fn pre_start( &self, myself: ActorRef, _: (), ) -> Result { // startup the event processing cast!(myself, Message::Ping)?; // create the initial state Ok(0u8) } // This is our main message handler async fn handle( &self, myself: ActorRef, message: Self::Msg, state: &mut Self::State, ) -> Result<(), ActorProcessingErr> { if *state < 10u8 { message.print(); cast!(myself, message.next())?; *state += 1; } else { println!(); myself.stop(None); // don't send another message, rather stop the agent after 10 iterations } Ok(()) } } #[tokio::main] async fn main() { let (_actor, handle) = Actor::spawn(None, PingPong, ()) .await .expect("Failed to start ping-pong actor"); handle .await .expect("Ping-pong actor failed to exit properly"); } ``` -------------------------------- ### Ractor Test Server Output Source: https://github.com/slawlor/ractor/blob/main/unit-tests-for-wasm32-unknown-unknown.md This console output indicates that the unit tests have been built and a local server has started. Access the provided URL in your browser to view test results. The server runs in interactive mode and can be stopped with Ctrl-C. ```console Interactive browsers tests are now available at http://127.0.0.1:8000 Note that interactive mode is enabled because `NO_HEADLESS` is specified in the environment of this process. Once you're done with testing you'll need to kill this server with Ctrl-C. ``` -------------------------------- ### Getting Process Group Members Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Retrieves a list of actor references that are currently members of the specified process group. ```rust use ractor::pg; let members = pg::get_members("my_group").await; println!("Group members: {:?}", members); ``` -------------------------------- ### Generate Rustls Test CA Source: https://github.com/slawlor/ractor/blob/main/ractor_cluster_integration_tests/test-ca/README.md Use this command to regenerate test certificate data for Rustls integration tests. Ensure you are in the correct directory and have the Rust toolchain installed. ```bash cargo run -p rustls --example test_ca ``` -------------------------------- ### Getting All Registered Actor Names Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Retrieves a list of all names currently registered in the Ractor named registry. This can be useful for introspection or dynamic discovery. ```rust use ractor::registry; let registered_names = registry::registered(); println!("Registered actors: {:?}", registered_names); ``` -------------------------------- ### Build Documentation Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Generate the project's documentation. Use the `-r` flag to build in release mode for more accurate performance-related documentation. ```bash # Build documentation carp doc --lib ``` ```bash # Build documentation in release mode carp doc --lib -r ``` -------------------------------- ### Run All Advanced Benchmarks with Cargo Source: https://github.com/slawlor/ractor/blob/main/docs/advanced_benchmarks.md Execute all benchmarks defined in the 'simple_advanced_benchmarks' file using Cargo. ```bash cargo bench --bench simple_advanced_benchmarks ``` -------------------------------- ### Run Linting and Formatting Checks Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Commands to run clippy for linting and rustfmt for checking code formatting. Use `--check` with rustfmt to avoid modifying files. ```bash # Run clippy carp clippy --all -- -D clippy::all -D warnings ``` ```bash # Run rustfmt carp fmt --all ``` ```bash # Check formatting without modifying carp fmt --all -- --check ``` -------------------------------- ### Profile Ractor Benchmarks with External Tools Source: https://github.com/slawlor/ractor/blob/main/docs/advanced_benchmarks.md Use these commands to analyze memory allocations, cache performance, lock contention, and memory usage for the simple_advanced_benchmarks suite. ```bash # Allocation profiling cargo instruments -t Allocations --bench simple_advanced_benchmarks # Cache analysis perf stat -e cache-references,cache-misses cargo bench --bench simple_advanced_benchmarks # Lock contention cargo flamegraph --bench simple_advanced_benchmarks -- --profile-time 60 # Memory usage heaptrack cargo bench --bench simple_advanced_benchmarks ``` -------------------------------- ### Compare Benchmark Results with SBO Feature Source: https://github.com/slawlor/ractor/blob/main/docs/advanced_benchmarks.md Compare benchmark results between a baseline configuration and one with the 'small-buffer-optimization' feature enabled. Requires saving results to files for comparison. ```bash # Baseline cargo bench --bench simple_advanced_benchmarks -- small_messages > /tmp/baseline.txt # With SBO cargo bench --bench simple_advanced_benchmarks --features small-buffer-optimization -- small_messages > /tmp/sbo.txt # Compare critcmp baseline.txt sbo.txt ``` -------------------------------- ### Run Benchmarks Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Execute performance benchmarks for the Ractor crate. This helps in identifying performance regressions. ```bash # Run benchmarks carp bench -p ractor ``` -------------------------------- ### Run Ractor Benchmarks Source: https://github.com/slawlor/ractor/blob/main/README.md Execute the performance benchmarks for the ractor crate. ```bash cargo bench -p ractor ``` -------------------------------- ### Run All Tests Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Execute all tests within the project. This is a fundamental step for ensuring code quality and stability. ```bash # Run all tests carp test ``` -------------------------------- ### Format and Lint Code Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Run these commands to format all code and perform strict linting. All errors and warnings must be resolved before declaring a code change complete. ```bash # Format all code (fix in place) carp fmt --all ``` ```bash # Run clippy with strict settings — ALL warnings must be resolved carp clippy --all -- -D clippy::all -D warnings ``` -------------------------------- ### Generate Coverage Report Source: https://github.com/slawlor/ractor/blob/main/xtask/README.md Execute the coverage task using the project's xtask runner. ```shell cargo xtask coverage --dev ``` -------------------------------- ### Run a Specific Test Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Execute a single test case by its name. This is helpful for quickly verifying a specific test or a small set of tests. ```bash # Run a specific test carp test --package ractor --test carp test --package ractor ``` -------------------------------- ### Connect to a Remote Node Server Source: https://github.com/slawlor/ractor/blob/main/ractor_cluster/README.md Use this function to establish a client connection to a remote NodeServer. Ensure nodes share a proper magic cookie for authentication. ```rust let host = "1.2.3.4"; let port = "4697"; ractor_cluster::client_connect( &actor, format!( "{host}:{port}") ) ``` -------------------------------- ### Spawn a standard actor Source: https://github.com/slawlor/ractor/blob/main/ractor_cluster/README.md Standard pattern for spawning an actor within the ractor framework. ```rust Actor::spawn(Some("name".to_string()), MyActor).await ``` -------------------------------- ### Run Tests for Specific Package Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Isolate and run tests for a particular crate within the workspace. Useful for targeted debugging. ```bash # Run tests for a specific package carp test --package ractor carp test --package ractor_cluster ``` -------------------------------- ### Run Specific Benchmark Category Source: https://github.com/slawlor/ractor/blob/main/docs/advanced_benchmarks.md Filter and run benchmarks belonging to a specific category, such as 'small_messages', 'large_messages', or 'spawn'. ```bash cargo bench --bench simple_advanced_benchmarks -- small_messages ``` ```bash cargo bench --bench simple_advanced_benchmarks -- large_messages ``` ```bash cargo bench --bench simple_advanced_benchmarks -- spawn ``` -------------------------------- ### Add ractor_cluster dependencies Source: https://github.com/slawlor/ractor/blob/main/ractor_cluster/README.md Include the ractor and ractor_cluster crates in your Cargo.toml file to enable cluster support. ```toml [dependencies] ractor = { version = "0.13", features = ["cluster"] } ractor_cluster = "0.13" ``` -------------------------------- ### Joining a Process Group Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Adds a list of actors to a named process group. Actors automatically leave the group upon shutdown. ```rust use ractor::pg; let actors_to_join = vec![actor_ref1, actor_ref2]; pg::join("my_group", actors_to_join).await; ``` -------------------------------- ### Using RpcReplyPort in RactorClusterMessage Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Demonstrates the usage of `RpcReplyPort` within an RPC variant of a `RactorClusterMessage`. The reply port can be at any position in the `#[rpc]` variant and there must be exactly one. ```rust #[derive(RactorClusterMessage)] enum ClusterMessageWithReply { ProcessData { data: Vec, reply_to: RpcReplyPort, }, #[rpc] FetchConfig(RpcReplyPort), } ``` -------------------------------- ### Compile Benchmarks Without Running Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Compile the benchmark code without executing it. This can be useful for checking compilation times or dependencies. ```bash # Compile benchmarks without running carp bench --no-run ``` -------------------------------- ### Run Tests with Feature Flags Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Execute tests with specific feature flags enabled or disabled. This allows testing different configurations and capabilities of the Ractor framework. ```bash # Run tests with specific feature flags carp test --package ractor --features cluster carp test --package ractor --features async-std,message_span_propogation --no-default-features carp test --package ractor --features monitors carp test --package ractor --features blanket_serde ``` -------------------------------- ### Auto-implement serialization for Protobuf types Source: https://github.com/slawlor/ractor/blob/main/README.md Use the derive_serialization_for_prost_type macro to automatically implement serialization for types defined with prost. ```rust ractor_cluster::derive_serialization_for_prost_type! {MyProtobufType} ``` -------------------------------- ### Implement Custom Cluster Transport Source: https://github.com/slawlor/ractor/blob/main/ractor_cluster/README.md Implement the ClusterBidiStream trait for custom transports like QUIC or WebSockets. The cluster protocol framing remains the same, but authentication and control logic are handled by the trait. ```rust use ractor_cluster::{ClusterBidiStream, BoxRead, BoxWrite}; use tokio::io::DuplexStream; struct MyDuplex(DuplexStream); impl ClusterBidiStream for MyDuplex { fn split(self: Box) -> (BoxRead, BoxWrite) { let (r, w) = tokio::io::split(self.0); (Box::new(r), Box::new(w)) } fn peer_label(&self) -> Option { Some("duplex:peer".into()) } fn local_label(&self) -> Option { Some("duplex:local".into()) } } // elsewhere in async context // let (a, b) = tokio::io::duplex(64 * 1024); // node_server.cast(NodeServerMessage::ConnectionOpenedExternal { stream: Box::new(MyDuplex(a)), is_server: false })?; ``` -------------------------------- ### Monitoring a Process Group Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Subscribes to `SupervisionEvent::ProcessGroupChanged` events for a specific process group. This allows an actor to be notified when the group's membership changes. ```rust use ractor::pg; pg::monitor("my_group", self.myself.clone().into()).await; ``` -------------------------------- ### Add Ractor Dependency to Cargo.toml Source: https://github.com/slawlor/ractor/blob/main/README.md Add the Ractor crate to your project's dependencies in Cargo.toml. Ensure your Rust version meets the minimum requirements for full async fn in traits support. ```toml [dependencies] ractor = "0.15" ``` -------------------------------- ### Spawning a Named Actor Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Spawns a new actor with a given name. The actor will be automatically registered in the named registry and unregistered upon its termination. ```rust use ractor::{Actor, ActorContext, ActorId, SupervisionEvent}; struct MyNamedActor; impl Actor for MyNamedActor { type State = (); type Ctx = ActorContext; fn state(ctx: &Self::Ctx) -> Self::State { () } async fn handle( &mut self, _msg: (), // Replace with actual message type _ctx: &mut Self::Ctx, ) -> SupervisionEvent { SupervisionEvent::Default } } let name = Some("my_actor_name".to_string()); let actor_ref = MyNamedActor::spawn(name, (), None).await.unwrap(); ``` -------------------------------- ### Auto-implement BytesConvertable for Prost Types Source: https://github.com/slawlor/ractor/blob/main/ractor_cluster/README.md This macro automatically implements the `BytesConvertable` trait for your protobuf types, allowing them to be serialized and deserialized. ```rust ractor_cluster::derive_serialization_for_prost_type!{MyProtobufType} ``` -------------------------------- ### Spawning a Thread-Local Actor Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Spawns an actor that can handle `!Send` types using the `ThreadLocalActor` trait. This requires the Tokio runtime with the `rt` feature enabled and uses `ractor::spawn_local()`. ```rust use ractor::{Actor, ActorContext, SupervisionEvent, ThreadLocalActor}; struct MyThreadLocalActor { state: String }; impl ThreadLocalActor for MyThreadLocalActor { type State = String; type Ctx = ActorContext; fn state(ctx: &Self::Ctx) -> Self::State { String::new() } async fn handle( &mut self, _msg: (), // Replace with actual message type _ctx: &mut Self::Ctx, ) -> SupervisionEvent { SupervisionEvent::Default } } let actor_ref = ractor::spawn_local(MyThreadLocalActor { state: "initial".to_string() }, None).await.unwrap(); ``` -------------------------------- ### Derive RactorClusterMessage for Remoting Source: https://github.com/slawlor/ractor/blob/main/ractor_cluster/README.md Use this derive statement to enable remoting for your actor. It adds boilerplate for serializing messages and handling RPC calls. ```rust use ractor_cluster::RactorClusterMessage; use ractor::RpcReplyPort; #[derive(RactorClusterMessage)] enum MyBasicMessageType { Cast1(String, u64), #[rpc] Call1(u8, i64, RpcReplyPort>), } ``` -------------------------------- ### Looking up an Actor by Name Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Retrieves an `ActorCell` for an actor that has been registered with a name. Returns `None` if no actor is found with the given name. ```rust use ractor::registry; if let Some(actor_cell) = registry::where_is("my_actor_name") { println!("Found actor: {:?}", actor_cell); } ``` -------------------------------- ### Deriving RactorClusterMessage for Remote-Capable Actors Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Use `#[derive(RactorClusterMessage)]` for enum message types that need to be sent between remote actors. This macro generates the necessary serialization code. Mark RPC variants with `#[rpc]`. ```rust #[derive(RactorClusterMessage)] enum ClusterMessage { Request(String), #[rpc] GetData(u32, RpcReplyPort), Response(String), } ``` -------------------------------- ### Deriving RactorMessage for Local Actors Source: https://github.com/slawlor/ractor/blob/main/CLAUDE.md Use `#[derive(RactorMessage)]` for enum message types intended for local-only actors. This macro marks messages as non-serializable. ```rust #[derive(RactorMessage)] enum LocalMessage { Ping, Pong, } ``` -------------------------------- ### Derive Basic RactorMessage Trait Source: https://github.com/slawlor/ractor/blob/main/ractor_cluster/README.md Derive the RactorMessage trait for local-only actors to quickly implement the default Message trait without manual implementation. This is suitable when messages do not need to be sent over the network. ```rust use ractor_cluster::RactorMessage; use ractor::RpcReplyPort; #[derive(RactorMessage)] enum MyBasicMessageType { Cast1(String, u64), Call1(u8, i64, RpcReplyPort>), } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.