docs.rs failed to build plexor-codec-capnp-0.1.0-alpha.2
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

Plexor Codec: Cap'n Proto

plexor-codec-capnp provides a high-performance binary codec implementation for the Plexor distributed system architecture using Cap'n Proto.

It is designed for scenarios requiring extremely low latency and high throughput, as Cap'n Proto messages avoid the heavy serialization/deserialization steps common in other formats.

Features

High Performance: Designed for low-latency messaging.
Schema Evolution: Robust handling of schema changes.
Plexor Integration: Implements Codec for plexor-core.
Flexible Mapping: Supports both raw Cap'n Proto types and ergonomic Rust structs via capnp_conv.

Note on Performance: While the Cap'n Proto format is highly efficient, using the capnp_conv mapping layer introduces a small amount of overhead when translating between native Rust structs and the Cap'n Proto memory layout. Although not quite as efficient as using raw Cap'n Proto readers and builders, it remains significantly faster than JSON (as shown in the benchmarks below). For absolute maximum performance where every microsecond counts, users should consider using the raw generated Cap'n Proto readers and builders directly.

Benchmarks

Comparison between plexor-codec-serde-json and plexor-codec-capnp (approximate values). Detailed benchmarks can be found in examples/codec-comparison-benchmark/.

Operation	Size	JSON (Serde)	Cap'n Proto (`capnp_conv`)	Speedup
Encode	100 B	~447 ns	~352 ns	~1.3x
Decode	100 B	~958 ns	~333 ns	~2.9x
Encode	10 KB	~31.6 µs	~5.5 µs	~5.7x
Decode	10 KB	~71.2 µs	~5.6 µs	~12.7x
Encode	1 MB	~3.2 ms	~513 µs	~6.2x
Decode	1 MB	~7.2 ms	~540 µs	~13.3x

Benchmarks run on a Framework 13 (AMD Ryzen 7 7840U, 32GB RAM) running Linux (x86_64).

Usage

1. Add Dependencies & Build Script

Cargo.toml:

[dependencies]
plexor-core = "0.1.0-alpha.1"
plexor-codec-capnp = "0.1.0-alpha.1"
capnp = "0.20"
capnp_conv = "0.3"

[build-dependencies]
capnpc = "0.20"

build.rs:

fn main() {
    capnpc::CompilerCommand::new()
        .file("schema/my_schema.capnp")
        // .output_path("src/schema/") // Optional: customize output
        .run()
        .expect("compiling schema");
}

2. Define Schema (my_schema.capnp)

@0x1234567890abcdef;

struct MyMessage {
  content @0 :Text;
  count @1 :UInt32;
}

3. Define Rust Struct & Neuron

Use capnp_conv to map your Rust struct to the Cap'n Proto schema.

use capnp_conv::capnp_conv;
use plexor_codec_capnp::CapnpCodec;
use plexor_core::neuron::NeuronImpl;
use plexor_core::namespace::NamespaceImpl;
use std::sync::Arc;

// Include the generated capnp code (adjust path as needed)
// include!(concat!(env!("OUT_DIR"), "/my_schema_capnp.rs")); 
// Or if you output to src:
mod my_schema_capnp { include!("schema/my_schema_capnp.rs"); }

#[derive(Debug, Clone)]
#[capnp_conv(my_schema_capnp::my_message)]
struct MyMessage {
    content: String,
    count: u32,
}

// Define the Neuron
let neuron = NeuronImpl::<MyMessage, CapnpCodec>::new_arc(
    Arc::new(NamespaceImpl {
        delimiter: ".",
        parts: vec!["my", "capnp", "message"],
    })
);

License

Mozilla Public License, version 2.0.

plexor-codec-capnp 0.1.0-alpha.2