[−][src]Trait stowaway::Stowable
Marker trait to indicate which types are safe to stow.
Currently, it is undefined behavior to read/write uninitialized memory in a primitive type, such as a pointer or usize, even if that memory is never "used". This means that types that have uninitialized bytes in their representation (such as structs with padding bytes) cannot be packed by stowaway, even if they would otherwise fit. It's not currently possible to detect if a struct might contain uninitialized bytes, so any types that want to be stowed must implement this trait.
This trait is implemented for most primitive and standard library types you might want to stow:
- All integer & float types.
boolandchar.- All primitive pointer types.
- All arrays of
Stowable(up to length 32, until const generics are stable) - All structured pointer types (
Rc,Arc, etc)
Safety
Correct usage of this trait is critical to stowaway's safety guarantees.
This struct can only be implemented on types that can never have
uninitialized bytes anywhere in their representation (including padding
bytes). Making this determination isn't trivial, though typically it's
safe if sizeof(T) == sum(sizeof(fields in T)), and all of the fields in
T are themselves Stowable.
Structs which are repr(transparent) are Stowable if their inner field
is Stowable.
This trait can be safely derived for any struct with 0 or 1 field:
use stowaway::Stowable; use std::sync::Arc; #[derive(Debug, Clone, Stowable)] struct ItemHandle<T> { ptr: Arc<T> }
use stowaway::Stowable; // This will not work; TwoFields has two fields #[derive(Stowable)] struct TwoFields { a: usize, b: usize, }
use stowaway::Stowable; // This will not work; the inner field isn't stowable struct NotStowable { ptr: Arc<usize>, } #[derive(Stowable)] struct Handle { ptr: NotStowable, }