What #[derive(Durable)] generates, and why.
What it generates
For a struct or enum, four things:
- a
Durableimplementation —FIXED_SIZE,encoded_len,encode,decode, and the schema descriptor; - a
Muttype,MyTypeMut, with a_mut()accessor per field, aparts()method handing out aMutfor every field at once, and a whole-valueset; - a
Derefimplementation on theMut, so read-only methods stay available — and noDerefMut, which would hand out a&mutwhose changes no journal record describes; - with
#[kladde(bounded)], aBoundedimplementation: the fixed form.
#[derive(Durable)]
struct Point { x: f32, label: String, n: u32 }generates, in essence:
impl Durable for Point {
const FIXED_SIZE: Option<usize> = sum_sizes(&[f32::FIXED_SIZE, String::FIXED_SIZE, u32::FIXED_SIZE]);
fn encoded_len(&self) -> usize { self.x.encoded_len() + self.label.encoded_len() + self.n.encoded_len() }
fn encode(&self, out: &mut Encoder<'_>) { self.x.encode(out); self.label.encode(out); self.n.encode(out) }
fn decode(input: &mut Decoder<'_>) -> Result<Self, Error> {
Ok(Point { x: f32::decode(input)?, label: String::decode(input)?, n: u32::decode(input)? })
}
// ...
}
impl<'r, B: Backend> PointMut<'r, B> {
fn label_mut(&mut self) -> StringMut<'_, B> {
let offset = 4; // after `x`, whose size is fixed
let len = self.inner.label.encoded_len();
self.inner.label.mutate(self.region.child(offset, len, None, 1))
}
fn n_mut(&mut self) -> SetMut<'_, u32, B> {
let offset = 4 + self.inner.label.encoded_len(); // after a field whose size varies
let len = self.inner.n.encoded_len();
self.inner.n.mutate(self.region.child(offset, len, None, 2))
}
}A field’s accessor makes a child region at the sum of the sizes of the fields before it: a constant up to the first field whose FIXED_SIZE is None, folded by the compiler, and after that the sum of the earlier fields’ encoded sizes, which the in-memory values give in constant time.
The child region reports a change of the field’s size to the struct’s region, which passes it on up.
parts() makes every field’s Mut at once, from a FieldSizes node it fills with the fields’ sizes: a field after the first variable-size one is indexed, and looks its start up in the node at every write, so that a sibling before it may change size meanwhile (handles made together).
The aggregate records nothing of its own
A struct is its fields’ encodings back to back, so its Mut has nothing of its own to write beyond set.
Every accessor just makes a child region and the field’s own Mut, recursively.
This is why the macro is small: it computes offsets and forwards; all the actual work is in the leaf types.
Fixed forms
#[kladde(bounded)] implements Bounded, the fixed form that Fixed<T> holds: every field’s fixed form, back to back, and for an enum the discriminant at a fixed width and its variant padded with zeros to the largest.
It requires every field’s type to be Bounded, failing at the type’s definition otherwise, with the message #[diagnostic::on_unimplemented] gives, and bounds each type parameter by Bounded, so that a generic type such as Tagged<T> is Bounded where its parameter is.
The derive cannot implement Bounded unasked, exactly where the fields’ types allow it: for a type without parameters, rustc refuses an impl whose where-clause names a concrete type that lacks the trait (E0277) rather than dropping the impl, short of the unstable trivial_bounds.
So the author opts in.
Opting in marks only the types that Fixed wraps and those inside them, none in kladde-svg; opting out would mark every type that holds text, a container or itself, 6 of kladde-svg’s 15 derived types.
Primitives are Durable too
i32, bool, char and friends have implementations, specifically so the macro can treat every field uniformly rather than special-casing leaves.
Those implementations must live in the crate that defines Durable, because impl Durable for i32 is impl ForeignTrait for ForeignType from anywhere else, which the orphan rules forbid; the same reasoning forces the scalar Mut types into that crate.
The same holds for String and Vec<T>, whose Durable implementations live in kladde-persist beside the scalars’.
Enums
An enum is its discriminant as a varint, followed by the selected variant’s fields, each variant encoded like a struct in its own right. It is fixed-size if every discriminant is below 128 and every variant takes the same fixed size. The discriminant is Rust’s own: the explicit value where the author wrote one, otherwise one more than the previous variant’s.
In the schema, every variant holds exactly one value, as the Enum descriptor has it, so the derive picks the value’s type by the variant’s shape:
- a unit variant holds
(), the empty struct; - a variant with one unnamed field holds that field’s type;
- any other variant holds an anonymous struct of its fields, named after the variant, its positional fields named by position —
"0","1".
So enum E { R { w: u32, h: u32 } } and enum E { R(Rect) } with struct Rect { w: u32, h: u32 } have the same fingerprint and the same bytes, and moving a variant’s fields into a struct of their own changes nothing on file.
Option’s None holds () too.
The discriminant’s width in the fixed form is as wide as its values need, unless an integer #[repr] fixes it.
#[repr(u8)], u16, u32 or u64 sets the width; without one, it is the smallest of 1, 2, 4 and 8 bytes that holds the largest discriminant value, the widths the Enum descriptor allows.
A signed or pointer-sized repr, and a negative discriminant, do not compile, since descriptors store discriminants unsigned and usize has no fixed width.
Without a repr, the width is a cliff: a 257th variant, or a discriminant of 256 or more, widens every Fixed value of the type; a repr keeps the fixed form’s size when variants are added.
The Mut’s parts() hands out the Muts of the current variant’s fields, as a generated enum {Enum}Parts with the same variants, so a field is mutated in place by matching:
match shape_mut.parts() {
ShapeParts::Circle(mut radius) => radius.set(2)?,
ShapeParts::Rectangle { mut width, .. } => width.set(3)?,
ShapeParts::Origin => {}
}Each field’s Mut is based at the field’s offset past the discriminant’s varint and writes inside its field only, so the discriminant cannot change underneath it.
And parts() borrows the enum’s Mut, so set cannot switch the variant while a field’s Mut is alive.
set is how the variant changes: it splices the new value’s encoding over the old one’s.
parts() on a temporary Mut works in a match but not in a let … else, which drops the temporary at the end of the statement; a consuming into_parts(self) would make the let form work too, and is proposed rather than built.
An enum without any fields gets no parts(), since it has nothing to mutate in place.
Trait objects, as an enum
A file can hold only values whose types it can name, so where an application would hold a Box<dyn Shape>, it holds an enum of the shapes, which implements Shape by forwarding every method to its current variant.
The trait is marked #[kladde::dispatch], and the enum #[kladde(dispatch(Shape))] beside #[derive(Durable)]; every variant holds one value, of a type that implements the trait.
The derive also implements From for every variant’s type, and for the T of a variant that holds a Box<T>, so AnyShape::from(Circle { .. }) builds the right variant.
On file the enum is an ordinary enum, with a variant per implementation, so the schema needs nothing new, and a C++ or Python implementation reads it as it reads any enum.
A variant may hold its value in a Box, to keep a large variant from making every value of the enum large in memory: a box is persisted as what it holds, its Mut is the Mut of what it holds, and it is Bounded where what it holds is, so boxing or unboxing a variant changes neither the file nor the fingerprint.
Why an enum rather than Box<dyn Trait> itself.
Rust cannot list a trait’s implementations, so the variants have to be listed somewhere, and an enum is the list Rust already checks: two variants with the same explicit discriminant fail to compile (E0081), and a variant’s type that does not implement the trait fails at the enum.
A reader has to know every variant to decode a file, so the openness of dyn would buy nothing on file; collecting implementations from several crates at link time would make the fingerprint depend on which crates a binary linked.
And Durable cannot be used through dyn — it requires Sized, has associated constants and a generic Mut, and decode returns Self — so a durable Box<dyn Shape> would need a helper trait, a table of decoders, and Muts reached by downcasting, where the enum gets parts() and an exhaustive match.
The enum is also faster, with no vtable and no allocation per value.
How the two macros meet.
A derive sees only the enum, never the trait’s methods, so #[kladde::dispatch] emits, beside the unchanged trait, a hidden macro_rules! macro, __kladde_dispatch_Shape, that knows the methods and writes the forwarding impl for an enum it is handed; it re-exports it next to the trait with pub(crate) use.
The derive invokes it by the trait’s path, with the trait’s module path and the macro’s name in place of the trait’s, so the enum may be in any module, before or after the trait.
For each variant it passes the pattern binding the held value, the value’s type, and how to reach the value by reference, by mutable reference and by value, through the box for a variant that holds one; and the impl’s where clause, with a bound of the trait on each variant’s type, spanned at that type, so that a missing implementation is reported at the enum, and a generic enum gets the bounds it needs.
This is the pattern of the ambassador crate; enum_dispatch instead passes the trait’s tokens through global state between the two macros, which depends on the order rustc expands them in.
What it forwards.
Every method of the trait, defaulted ones included, so that a variant’s own implementation wins: methods taking self, &self or &mut self, generic ones, async ones, unsafe ones, and ones with impl Trait arguments.
It refuses, at the trait, what it cannot forward: a method without a receiver, which no enum could choose a variant for; one that takes Self other than as its receiver, or returns Self or impl Trait, since each variant would bring or return a type of its own; and associated types and constants, which each variant may choose differently, and generic traits.
A variant’s type that two variants hold gets no From, nor does one that mentions a type parameter, since From<T> would overlap with every other variant’s.
Limitations.
The trait and the enum must be in one crate: a macro_rules! macro can be public only through #[macro_export], which puts it at the crate root, where a macro-expanded one may not be named by path from its own crate.
A box is recognized by its spelling, Box<T>, std::boxed::Box<T> or alloc::boxed::Box<T>, so a variant holding a box behind a type alias forwards to the box itself, which then has to implement the trait.
Generics and transparency
Type parameters are supported: each gets a Durable bound, the heuristic #[derive(Debug)] uses.
Lifetime and const parameters are rejected.
#[kladde(transparent)] on a single-field struct persists it exactly as its field — same bytes, same descriptor, same fingerprint — and gives its Mut one get_mut() returning the field’s Mut, as #[serde(transparent)] does.
Path resolution
Generated code names items by absolute path, because a macro cannot know what the user called their imports.
It roots them at ::kladde, and kladde re-exports every item generated code or a hand-written impl names, so an application depends on kladde and nothing below it.
That matters for more than convenience: if the facade did not re-export them, an author would add kladde-persist themselves, and a version that disagreed with the facade’s would produce two distinct copies of the Durable trait and an error that prints the expected and found types identically.
A library built directly on kladde-persist has no reason to pull the facade in, and redirects the macro instead, as serde’s #[serde(crate = "...")] does:
#[derive(Durable)]
#[kladde(crate = "kladde_persist")]
struct Node { /* ... */ }What is missing
Field attributes.
There is no #[kladde(skip)] for a non-persisted field, no #[kladde(id = ...)] for rename-robust identity, and no way to declare a default for a field added later.
The last two become necessary when evolution lands.
Two more, modeled on serde’s, would serve types the derive cannot handle today:
#[kladde(with = "path")]on a field of a type that is notDurable, a foreign one or one wanting an encoding of its own, delegating its encoding, descriptor andMutto a module of functions, so that a foreign type can be encoded inline with a real descriptor rather than wrapped in aDurableBlob.#[kladde(bound = "...")]on the type, overriding theDurablebound the derive puts on every type parameter, for a parameter used only inPhantomData, or only inside a wrapper that needs a different bound.
Const generic parameters, which the derive rejects today.
Conveniences on Muts: set_<field>(value) on a struct’s Mut, sparing the step through the field’s accessor, and field_{i}_mut() on a tuple’s Mut, which offers only parts() and set, as tuple structs’ Muts offer it.
A tuple’s accessors cannot be generated by macro_rules! without a crate such as paste to build their names.
Testing compile failures
The macro’s compile errors are part of its contract — a field of a type that is not Durable, such as a PathBuf, must fail to compile, and that is the mechanism preventing silent data loss.
These are tested with rustdoc compile_fail doctests rather than a separate harness, which keeps the expected-failure cases next to the documentation that explains them.