zeekay
ed429a2283
Cap'n Proto was the canonical name for this Rust implementation. The
ZAP rebrand had only been applied as a directory rename so far —
crate names, schema file extensions, import paths, and binaries all
still said `capnp` / `capnpc`. This commit makes the rebrand real.
Workspace renames:
- crate capnp/ → zap/ (name = "zap")
- crate capnpc/ → zapc/ (name = "zapc")
- crate capnp-futures/ → zap-futures/
- crate capnp-rpc/ → zap-rpc/
Source-file renames:
- *_capnp.rs → *_zap.rs (~12 files: schema_zap.rs, rpc_zap.rs, etc.)
- capnpc-rust.rs → zapc-rust.rs (the codegen binary entry point)
- *.capnp → *.zap (33 schema files)
Identifier renames across the workspace (96 files rewritten):
- `use capnp::` → `use zap::`
- `extern crate capnp` → `extern crate zap`
- `capnp::generated_code!` → `zap::generated_code!`
- `capnp::traits::Owned` → `zap::traits::Owned`
- `capnp::message::...` → `zap::message::...`
- `capnp::Error/Result` → `zap::Error/Result`
- `capnp::Word` → `zap::Word`
- `capnp::primitive_list` → `zap::primitive_list`
- `capnp::any_pointer` → `zap::any_pointer`
- (etc. — see python script in commit history for full list)
Cargo.toml dep keys:
- `capnp = { path = ... }` → `zap = { path = ... }`
- `[dependencies.capnp]` → `[dependencies.zap]`
- `capnpc = { ... }` → `zapc = { ... }`
- Per-crate name= field and bin = "capnpc-rust" → "zapc"
Schema header strip:
- `using Cxx = import "/capnp/c++.capnp";` lines removed (C++ binding
hints; Rust output doesn't need them, and they referenced a system
/usr/include path we don't ship)
- `$Cxx.namespace("capnp::...")` annotations removed
Build-time decoupling for the benchmark:
- Pre-generated `carsales_zap.rs`, `catrank_zap.rs`, `eval_zap.rs` are
now committed in benchmark/. benchmark/build.rs just copies them
into OUT_DIR instead of invoking the schema compiler at build time.
- benchmark/Cargo.toml drops the [build-dependencies] zapc entry.
Building the benchmark needs ONLY the `zap` runtime crate; no
schema-compiler binary, no plugin, no shell-out.
To regenerate the schema-bound .rs from .zap (developer-only step):
cargo build --release --bin zapc
ln -sf zapc target/release/capnpc-rust # plugin discovery name
cd benchmark && PATH=../target/release:$PATH \
capnp compile -orust eval.zap catrank.zap carsales.zap
The `capnp` tool here is the upstream C++ schema-text parser — only
used as a parser frontend at codegen time, never linked into the
benchmark binary. Runtime + build = 100% zap/zapc only.
Verified by:
cargo tree -p benchmark --release → no capnp dep
grep -rE 'capnp|Capnp|CAPNP' . → 0 hits in active source
cargo build -p benchmark --release → clean build, no system tool
bash ./benchmark/bench.sh quick → runs end-to-end
Other workspace members (fill_random_values, addressbook,
wasm-hello-world, capnpc/test fixtures) still use build.rs schema
compilation at build time; they require a `zap` binary in PATH.
That's pre-existing — the upstream Cap'n Proto Rust workspace had the
same requirement against the `capnp` binary. Out of scope for this PR.
3.9 KiB
layout, title, author
| layout | title | author |
|---|---|---|
| post | new feature to allow unaligned buffers | dwrensha |
Last week I wrote about how zap-rust might relax its memory alignment requirements and what the performance cost of that might look like. The ensuing discussion taught me that memory alignment issues can be thornier than I had thought, and it strengthened my belief that zap-rust users ought be shielded from such issues. Since then, working with the helpful feedback of many people, I have implemented what I consider to be a satisfactory resolution to the problem. Today I'm releasing it as part of zap-rust version 0.12. The new version not only provides a safe interface for unaligned memory, but also maintains high performance for aligned memory.
New Feature Flag
Cargo supports a feature-flags mechanism, whereby a crate can declare parts of its functionality to be optional, with enablement or disablement happening at compile time.
As of version 0.12, the zap crate has a new
feature flag called unaligned.
When unaligned is enabled, zap makes no assumptions about the alignment of its data.
In particular, it can read a message in place from any array of bytes via
read_message_from_flat_slice().
On the flip side, when unaligned is not enabled, zap requires that message segments are 8-byte aligned,
returning an error
if it detects that's not the case.
The 8-byte alignment is then used whenever
zap loads or stores a primitive value in a message.
With the new interface, there is no longer a need for the problematic unsafe fn Word::bytes_to_words(),
so that method no longer exists.
Performance
The downside of enabling the unaligned feature is that some operations require
more instructions on certain compilation targets.
To better understand the performance cost,
I ran zap-rust's
benchmark suite
on three different computers: my laptop (x86_64), an EC2 ARM64 instance (aarch64), and a Raspberry Pi Zero (armv6).
I compared three different zap-rust versions: 0.11, 0.12, and 0.12 with unaligned.
As expected, on all of the computers
the 0.12 version without the unaligned feature performed about the same version 0.11
(within measurement noise).
When I enabled the unaligned feature, the only computer where there
was a noticeable performance impact was the Raspberry Pi,
where the benchmarks slowed down between 10 and 20 percent.
This also was within my expectations, though I had been hoping
it would be lower. (If the performance impact had been negligible,
I would likely not have bothered to make unaligned an optional feature; instead
I would have made it the only supported mode.)
Validation
Following ralfj's suggestion, I also performed some testing with miri to increase my confidence that there is no lurking undefined behavior. I added some tests that specifically force 1-byte alignment.
I was pleasantly surprised to learn how easy it is to run miri these days:
$ rustup component add miri
$ cargo miri test
I recommend that you try this on your own projects!