Module fxfs::serialized_types

source ·
Expand description

On-disk versioning

This module manages serialization and deserialization of FxFS structures to disk.

In FxFS, on-disk layout is deferred to serialization libraries (i.e. bincode, serde). Stability of these layouts depends on both struct/enum stability and serialization libraries.

This module provides struct/enum stability by maintaining a generation of types and a means to upgrade from older versions to newer ones.

The trait mechanism used is flexible enough to allow specific versions to use differing serialization code if we ever require it.

Traits

All serialization is done with serde so Serialize and Deserialize traits must be derived for all types and sub-types.

All versioned, serializable struct/enum type should have the Versioned trait. The most recent version of a type should also have the VersionedLatest trait. These traits are largely implemented for you via the versioned_type! macro as follows:

versioned_type! {
  3.. => SuperBlockHeaderV3,
  2.. => SuperBlockHeaderV2,
  1.. => SuperBlockHeaderV1,
}

// Note the reuse of SuperBlockRecordV1 for two versions.
versioned_type! {
  3.. => SuperBlockRecordV2,
  1.. => SuperBlockRecordV1,
}

The user is required to implement From to migrate from one version to the next. The above macros will implement further From traits allowing direct upgrade from any version to the latest. VersionedLatest provides a deserialize_from_version method that can be used to deserialize any supported version and then upgrade it to the latest format.

Conventions

There are limits to how automated this process can be, so we rely heavily on conventions.

  • Every versioned type should have a monotonically increasing Vn suffix for each generation.
  • Every versioned sub-type (e.g. child of a struct) should also have Vn suffix.
  • In type definitions, all versioned child types should be referred to explicitly with their Vn suffix. This prevents us from accidentally changing a version by changing a sub-type.

Macros

Structs

Constants

Traits

  • This trait is assigned to all versions of a versioned type and is the only means of serialization/deserialization we use.
  • This trait is only assigned to the latest version of a type and allows the type to deserialize any older versions and upgrade them to the latest format.

Attribute Macros

  • This does nothing by itself, but with the Migrate derive macro, it signals that the struct being migrated to, does not require a Default implementation, since all the fields are available in both.
  • This does nothing by itself, but with the Migrate derive macro, it defines the target to migrate to. Without this, Migrate will make a From impl for IdentVX to Ident.

Derive Macros

  • Adds a From implementation to help migrate structs or enums. This will support the following migrations:
  • This is just a shorthand for impl Versioned for Foo {} which is required for all top-level versioned struct/enum in Fxfs.