mod.rs

Overview

This file defines the core data structure ZeroState and its associated methods, which represent the initial or root state of a multi-threaded blockchain shard system. It handles collections of optimistic states and block keeper sets indexed by thread identifiers, providing interfaces to access, modify, and initialize these per-thread states. The file also imports auxiliary modules responsible for parsing, serialization, and updating functionality related to the zero state.

The ZeroState struct acts as a container that maintains the mapping from each thread to its optimistic state and block keeper set. It offers operations to retrieve shard states, access thread tables, and manage the lifecycle of thread-specific data. This file is central to managing the system's view of the shard state at genesis or reset points and interacts closely with types and modules involved in optimistic state management and block keeping.

Modules and Imports

• Submodules:

  • parse: Handles parsing logic for zero state data (details not included here).

  • serialize: Public module for serialization of zero state data.

  • update: Contains logic for updating zero state instances (details not included here).

• External crates and modules used:

  • serde::{Deserialize, Serialize}: Serialization/deserialization traits for ZeroState.

  • tvm_block::ShardStateUnsplit: Represents an unsplit shard state, used for shard state retrieval.

  • std::collections::HashMap: Data structure for mapping thread identifiers to states and block keeper sets.

  • std::sync::Arc: Thread-safe reference counting pointer, used to share ShardStateUnsplit.

  • Application-specific imports:

    • BlockKeeperSet from block_keeper_system

    • OptimisticState and OptimisticStateImpl from repository::optimistic_state

    • ThreadIdentifier and ThreadsTable from types

Struct: ZeroState

pub struct ZeroState {
    states: HashMap<ThreadIdentifier, OptimisticStateImpl>,
    block_keeper_set: HashMap<ThreadIdentifier, BlockKeeperSet>,
}

Description

ZeroState maintains two primary collections keyed by ThreadIdentifier:

• states: A map from thread ID to the corresponding OptimisticStateImpl instance, representing the optimistic state of that thread.

• block_keeper_set: A map from thread ID to BlockKeeperSet, which manages blocks for that thread.

This design supports multiple threads operating in parallel with their own state and block keeping logic, while still allowing centralized access and management.

Traits Derived

• Debug - Enables formatting for debugging.

• Default - Provides a default empty ZeroState.

• Serialize and Deserialize - Enables conversion to/from serial formats (e.g., JSON, binary).

Methods on ZeroState

get_shard_state

pub(crate) fn get_shard_state(
    &mut self,
    thread_identifier: &ThreadIdentifier,
) -> anyhow::Result<Arc<ShardStateUnsplit>>

• Purpose: Retrieves the shard state associated with a given thread by delegating to the optimistic state.

• Parameters:

  • thread_identifier: Reference to the thread ID whose shard state is requested.

• Returns: A thread-safe shared pointer (Arc) to the ShardStateUnsplit or an error if the thread does not exist.

• Usage:

  let shard_state = zero_state.get_shard_state(&thread_id)?;
  

get_threads_table

pub fn get_threads_table(&self) -> &ThreadsTable

• Purpose: Returns a reference to the ThreadsTable shared by all optimistic states in the zero state.

• Details: Assumes all optimistic states share the same ThreadsTable. Panics if no states exist.

• Returns: Reference to the ThreadsTable.

• Usage:

  let threads_table = zero_state.get_threads_table();
  

get_block_keeper_set

pub fn get_block_keeper_set(&self) -> anyhow::Result<BlockKeeperSet>

• Purpose: Returns the single, unified BlockKeeperSet from the zero state.

• Details: The implementation expects exactly one block keeper set due to a design decision related to dynamic thread ID generation.

• Returns: A cloned BlockKeeperSet or an error.

• Usage:

  let bk_set = zero_state.get_block_keeper_set()?;
  

unwrapped_block_keeper_sets

pub fn unwrapped_block_keeper_sets(&self) -> &HashMap<ThreadIdentifier, BlockKeeperSet>

• Purpose: Provides access to the internal map of thread IDs to their block keeper sets.

• Returns: Reference to the internal HashMap.

• Usage:

  let bk_sets_map = zero_state.unwrapped_block_keeper_sets();
  

states

pub fn states(&self) -> &HashMap<ThreadIdentifier, OptimisticStateImpl>

• Purpose: Returns an immutable reference to the map of optimistic states.

• Returns: Reference to the internal HashMap.

• Usage:

  let states_map = zero_state.states();
  

states_mut

pub fn states_mut(&mut self) -> &mut HashMap<ThreadIdentifier, OptimisticStateImpl>

• Purpose: Returns a mutable reference to the map of optimistic states.

• Returns: Mutable reference to the internal HashMap.

• Usage:

  let states_map_mut = zero_state.states_mut();
  

state_mut

pub fn state_mut(
    &mut self,
    thread_identifier: &ThreadIdentifier,
) -> anyhow::Result<&mut OptimisticStateImpl>

• Purpose: Gets a mutable reference to the optimistic state for a specific thread.

• Parameters:

  • thread_identifier: The thread ID.

• Returns: Mutable reference to the optimistic state or an error if not found.

• Usage:

  let state_mut_ref = zero_state.state_mut(&thread_id)?;
  

state

pub fn state(
    &self,
    thread_identifier: &ThreadIdentifier,
) -> anyhow::Result<&OptimisticStateImpl>

• Purpose: Gets an immutable reference to the optimistic state for a specific thread.

• Parameters:

  • thread_identifier: The thread ID.

• Returns: Reference to the optimistic state or an error if not found.

• Usage:

  let state_ref = zero_state.state(&thread_id)?;
  

init_thread

pub fn init_thread(&mut self, thread_identifier: ThreadIdentifier)

• Purpose: Initializes a new thread entry in the zero state with a default optimistic state.

• Parameters:

  • thread_identifier: The thread ID to be initialized.

• Details: Creates an OptimisticStateImpl with the given thread ID and inserts it into the states map.

• Usage:

  zero_state.init_thread(new_thread_id);
  

set_threads_table

pub fn set_threads_table(&mut self, threads_table: ThreadsTable)

• Purpose: Updates the ThreadsTable for all optimistic states in the zero state.

• Parameters:

  • threads_table: The new ThreadsTable instance to set.

• Details: Clones the new table into each optimistic state.

• Usage:

  zero_state.set_threads_table(new_threads_table);
  

list_threads

pub fn list_threads(&self) -> impl Iterator<Item = &'_ ThreadIdentifier>

• Purpose: Returns an iterator over all thread identifiers currently in the zero state.

• Returns: An iterator yielding references to thread IDs.

• Usage:

  for thread_id in zero_state.list_threads() {
      // process thread_id
  }
  

Important Implementation Details

• The zero state maintains thread-local optimistic states and block keeper sets, allowing parallel thread management.

• It uses HashMap for efficient lookup by ThreadIdentifier.

• The get_block_keeper_set method assumes a single block keeper set exists, reflecting a design shift to unify block keeper sets due to dynamic thread ID generation.

• Arc<ShardStateUnsplit> is returned by get_shard_state to allow safe sharing of shard state without cloning the entire state.

• ThreadsTable is expected to be uniform across all optimistic states within the zero state.

• Error handling uses anyhow::Result with formatted error messages for missing threads or states.

Interactions with Other Components

• Utilizes OptimisticStateImpl for thread-specific optimistic state representation, which likely encapsulates state transitions and thread logic.

• Interacts with BlockKeeperSet to manage block data per thread.

• Returns ShardStateUnsplit references for integration with shard-level operations.

• Depends on ThreadIdentifier and ThreadsTable types to organize threading and scheduling data.

• The parse, serialize, and update modules complement this file by providing functionality for parsing zero state data, serialization for persistence or network transfer, and updating zero state instances.

Visual Diagram

classDiagram
class ZeroState {
-states: HashMap<ThreadIdentifier, OptimisticStateImpl>
-block_keeper_set: HashMap<ThreadIdentifier, BlockKeeperSet>
+get_shard_state()
+get_threads_table()
+get_block_keeper_set()
+unwrapped_block_keeper_sets()
+states()
+states_mut()
+state_mut()
+state()
+init_thread()
+set_threads_table()
+list_threads()
}
ZeroState --> "0..*" OptimisticStateImpl : states
ZeroState --> "0..*" BlockKeeperSet : block_keeper_set