Expand description
§Piying
Fault-tolerant async actors built on Tokio.
Piying is a fork of Kameo by tqwewe.
§Why fork?
- Larger production scope — Piying targets real-time networked games and other latency-sensitive distributed systems, driving changes to codec flexibility, networking, and error handling that go beyond upstream’s focus.
- AI-generated code welcome — the upstream project does not accept AI-generated contributions. Piying has no such restriction.
§Key differences from upstream
- Pluggable codec system (rkyv, serde, or custom) — decoupled from the core actor framework
PiyingRkyvCodecfor high-performance binary serialization via rkyv- Various networking and swarm improvements for production P2P use
§Installation
Add Piying to your Cargo dependencies:
[dependencies]
piying = "0.3"The default features enable actor macros and tracing. Optional remote networking
is layered, and needs serde-codec or rkyv-codec:
remote: messaging core (request-response,remote::Behaviour,#[remote_message]). Bring your own libp2p swarm. No Kademlia, mDNS or transports are compiled in.remote-registry: adds Kademlia nameregister/lookupacross the network.remote-bootstrap: addsremote::bootstrap()(mDNS, TCP, QUIC); impliesremote-registry.
See the API documentation for actor and messaging examples.
§Migrating to 0.3.0
remote is now messaging-only. Replace remote with remote-bootstrap to keep the
previous behaviour, or remote-registry if you build your own swarm but still use
Kademlia name lookup. Without remote-registry, ActorRef::register and
ActorRef::lookup are the synchronous in-process versions.
§Migrating to 0.2.0
ActorPool worker errors now preserve SendError<M, R::Error> rather than only
the handler error. Callers matching a pool’s handler failure must handle that
nested send-error type.
Piying 0.2.0 requires libp2p 0.57.0 for consumers that compose Piying’s
network behaviours or exchange libp2p types with Piying. Custom request-response
codecs implement libp2p’s native async methods without #[async_trait]. The
minimum Rust version remains 1.88.0.
registry::Event::RoutingUpdated::addresses is now Box<kad::Addresses> to
keep the larger upstream address collection out of every remote event. Borrowed
access works through dereferencing; use *addresses when moving the collection
into code that expects an owned kad::Addresses.
The remote-bootstrap feature requires hickory-proto 0.26.3 or later in the 0.26 series to
resolve RUSTSEC-2026-0118 and RUSTSEC-2026-0119. The existing rkyv framing helpers
remain supplied by libp2p-rkyv-codec 0.3; Piying implements the libp2p 0.57
codec itself. Remote protocol identifiers and the THSP version-2 rkyv framing
remain unchanged.
§Upstream features (inherited)
- Lightweight async actors on Tokio
- Fault tolerance with supervision strategies
- Flexible messaging (bounded/unbounded channels, backpressure)
- Local and distributed communication via libp2p
- Panic safety and actor isolation
- Type-safe message interfaces
§Development
Run nix develop for the pinned Rust tools, Just, and Simit 0.21.0
(substituted from the public canix Attic cache). Then:
just ci
simit init ci --check --diffGitHub Actions checks the entire workspace with all features and without
default features, including its declared minimum Rust version. The
minimal-library gate separately checks Piying’s library with no features and
with macros only; library-only checks avoid dev-dependencies re-enabling default
features. The required feature-matrix gate also runs just ci for
separate serde/rkyv lint and test runs, minimal-feature tests, and the
tokio_unstable build. The packaging gate checks workspace package contents
and verifies the macros crate archive. Both gates run before crate publishing
as well.
Publishing requires the GitHub repository secret CRATES_IO_API_TOKEN and a
signed version tag trusted by keys/maintainers.gpg. The workflow publishes
piying_macros, then piying, then piying_actors.
The signed tag must resolve to the immutable workflow event commit; a moved tag
fails validation before any release gates or publication run.
§License
Piying is dual-licensed under either:
- MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
Same as the original Piying project.
Re-exports§
Modules§
- actor
- Core functionality for defining and managing actors in Piying.
- error
- Defines error handling constructs for piying.
- mailbox
- A multi-producer, single-consumer queue for sending messages and signals between actors.
- message
- Messaging infrastructure for actor communication in Piying.
- prelude
- Commonly used types and functions that can be imported with a single use statement.
- remote
- Remote Actors in Piying
- reply
- Constructs for handling replies and errors in Piying’s actor communication.
- request
- Types for sending requests including messages and queries to actors.
Attribute Macros§
- messages
- Attribute macro placed on
implblocks of actors to define messages. - remote_
message - Registers an actor message to be supported with remote messages.
Derive Macros§
- Actor
- Derive macro implementing the Actor trait with default behaviour.
- Remote
Actor - Derive macro implementing the RemoteActor trait with a default remote ID being the full path of the type being implemented.
- Reply
- Derive macro implementing the Reply trait as an infallible reply.