optimistic_shard_state.rs

Overview

This file defines the OptimisticShardState abstraction, which encapsulates an underlying shard state representation that can exist either as a fully parsed structured form (ShardStateUnsplit), a raw serialized form (Cell), or both simultaneously. The design allows efficient lazy deserialization and serialization of shard states within a concurrent environment, supporting optimistic caching and mutation.

The core functionality revolves around managing these dual representations while providing thread-safe access and mutation through synchronization primitives. This approach optimizes performance by avoiding unnecessary conversions between structured and serialized forms unless explicitly required.

Key Components

Enum: OptimisticShardStateRepresentation

This enum represents the internal state of the shard data and has three variants:

• Both(Arc<ShardStateUnsplit>, Arc<Cell>)
  Holds both the structured ShardStateUnsplit and its serialized Cell representation simultaneously.

• AsShardState(Arc)
  Holds only the structured shard state.

• AsCell(Arc<Cell>)
  Holds only the serialized cell form of the shard state.

Implementation Details

• The enum is cloneable and supports guarded mutation via the AllowGuardedMut trait.

• This representation enables lazy conversion between structured and serialized forms on demand, which reduces overhead when only one form is needed in a particular context.

Struct: OptimisticShardState

The main struct encapsulating an OptimisticShardStateRepresentation inside a Mutex (from parking_lot) wrapped in an Arc to provide thread-safe shared ownership with interior mutability.

Fields

• data: Arc<Mutex<OptimisticShardStateRepresentation>>
  Thread-safe container for the internal representation.

Traits Implemented

• Clone
  Creates a deep copy by cloning the contained representation under lock.

• Debug
  Provides a debug formatter indicating which internal representations are present.

• Default
  Initializes with a default ShardStateUnsplit wrapped as AsShardState.

• From
  Multiple implementations to create an OptimisticShardState from:

  • Arc<ShardStateUnsplit>

  • (ShardStateUnsplit, Cell)

  • (Arc<ShardStateUnsplit>, Cell)

  • Cell

  • ShardStateUnsplit

• Serialize and Deserialize (with serde)
  Serialization always occurs through the Cell form. Deserialization produces an OptimisticShardState from a Cell.

Methods

make_an_independent_copy(&self) -> Self

Creates a new OptimisticShardState containing a clone of the current internal representation, ensuring complete independence from the original instance.

Usage Example:

let original: OptimisticShardState = ...;
let independent_copy = original.make_an_independent_copy();

into_cell(&self) -> Arc<Cell>

Returns the serialized Cell representation of the shard state. If the current representation lacks the cell form, it serializes the ShardStateUnsplit and updates the internal state to Both.

Important Implementation Detail:

• Serialization errors are handled by panicking (expect). This is acceptable here due to the synchronous, internal nature of the operation.

• Uses guarded mutable access to update internal representation safely.

into_shard_state(&self) -> Arc<ShardStateUnsplit>

Returns the structured ShardStateUnsplit representation. If only the Cell form is available, it deserializes the Cell into a ShardStateUnsplit, updates the internal state to Both, and returns the parsed state.

Implementation Notes:

• Deserialization errors cause panic via expect.

• Tracing statements (tracing::trace!) are included for lifecycle debugging.

• Uses Arc::make_mut to clone the shared cell for safe deserialization.

clone_representation(&self) -> OptimisticShardStateRepresentation

Provides a clone of the internal enum representation for external usage or inspection without locking the whole struct.

Serialization and Deserialization

• Serialization always targets the Cell form, ensuring a consistent wire format.

• Deserialization produces an OptimisticShardState initialized with the Cell variant.

• Uses custom serializers/deserializers (CellFormat) defined elsewhere (tvm_cell_serde::CellFormat).

Interaction with Other System Components

• Relies on ShardStateUnsplit from the tvm_block crate, which is the structured shard state representation.

• Uses Cell from tvm_types as the serialization primitive.

• The parking_lot::Mutex ensures internal locking without the performance penalties of standard library mutexes.

• Implements traits from serde and serde_with for data serialization.

• The AllowGuardedMut, Guarded, and GuardedMut utilities provide safe inner data access patterns, defined externally (crate::utilities::guarded).

• TypedBuilder is used to generate builder-pattern constructors for OptimisticShardState.

Important Implementation Details and Algorithms

• Lazy Conversion Between Representations:
  OptimisticShardState delays serialization/deserialization work until absolutely necessary, improving performance when only one form is used repeatedly.

• Thread-Safety via Arc<Mutex<...>>:
  Ensures safe concurrent access and mutation of the shard state representation.

• Cloning Strategy:
  The clone implementation clones the internal representation under lock, ensuring data consistency while avoiding race conditions.

• Serialization Strategy:
  Always serializes through the Cell representation to maintain a canonical wire format.

• Deserialization Strategy:
  Always produces a Cell variant, deferring structured parsing until requested.

Usage Examples

use std::sync::Arc;
use tvm_block::ShardStateUnsplit;
use tvm_types::Cell;

// Create OptimisticShardState from ShardStateUnsplit
let shard_state: Arc<ShardStateUnsplit> = Arc::new(ShardStateUnsplit::default());
let optimistic_state = OptimisticShardState::from(shard_state.clone());

// Get serialized cell representation
let cell: Arc<Cell> = optimistic_state.into_cell();

// Get structured shard state (deserializes if needed)
let parsed_shard_state: Arc<ShardStateUnsplit> = optimistic_state.into_shard_state();

// Clone representation
let cloned_repr = optimistic_state.clone_representation();

Mermaid Diagram: Structure of optimistic_shard_state.rs

classDiagram
class OptimisticShardState {
-data: Arc<Mutex<OptimisticShardStateRepresentation>>
+make_an_independent_copy()
+into_cell()
+into_shard_state()
+clone_representation()
}
class OptimisticShardStateRepresentation {
<<enum>>
+Both
+AsShardState
+AsCell
}
OptimisticShardState --> OptimisticShardStateRepresentation
OptimisticShardStateRepresentation o-- ShardStateUnsplit : contains
OptimisticShardStateRepresentation o-- Cell : contains

This diagram illustrates the core data structure, showing that OptimisticShardState contains a mutex-protected instance of the enum OptimisticShardStateRepresentation, which in turn holds either or both of ShardStateUnsplit and Cell instances.