cross_thread_ref_data.rs

Overview

This file defines the CrossThreadRefData structure, which encapsulates the minimal and complete data necessary for threads to reference the blockchain's state at a specific block. The structure stores references to a particular block's identity, sequence number, thread information, outbound messages and accounts, and thread spawning details. It serves as a data container facilitating cross-thread interactions and references within the system's multi-threaded consensus or state management mechanism.

The main functionality includes providing reference state information, managing thread tables and block references, and identifying newly spawned threads within a block's context.

Structure: CrossThreadRefData

Description

CrossThreadRefData holds essential data related to a blockchain block's state, enabling cross-thread referencing. It includes identifiers of the block and thread, outbound messages and accounts relevant only to the block, the threads table, and references to parent and other related blocks.

Fields

Traits Derived

• TypedBuilder: Enables builder pattern for constructing instances.

• Clone: Allows cloning of instances.

• Serialize and Deserialize: Support for serializing and deserializing data.

• Getters: Provides getter methods for all fields.

• Debug: Implements the Debug trait for formatting.

Methods

as_reference_state_data

pub fn as_reference_state_data(&self) -> (ThreadIdentifier, BlockIdentifier, BlockSeqNo)

Returns a tuple containing the thread identifier, block identifier, and block sequence number. This tuple represents the minimal reference state data for other components to identify the state this data refers to.

• Returns: (ThreadIdentifier, BlockIdentifier, BlockSeqNo)

• Usage Example:

  let (thread_id, block_id, seq_no) = cross_thread_ref_data.as_reference_state_data();
  

set_threads_table

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

Sets or updates the threads_table field with a new ThreadsTable instance.

• Parameters:

  • threads_table: The new threads table to be set.

• Usage Example:

  cross_thread_ref_data.set_threads_table(new_threads_table);
  

set_block_refs

pub fn set_block_refs(&mut self, block_refs: Vec<BlockIdentifier>)

Sets or updates the block_refs field with a vector of new block identifiers.

• Parameters:

  • block_refs: Vector of block identifiers to be set.

• Usage Example:

  cross_thread_ref_data.set_block_refs(vec_of_block_ids);
  

get_produced_threads_table

pub fn get_produced_threads_table(&self) -> &ThreadsTable

Returns a reference to the stored threads_table.

• Returns: Reference to ThreadsTable.

• Usage Example:

  let threads_table = cross_thread_ref_data.get_produced_threads_table();
  

refs

pub fn refs(&self) -> &Vec<BlockIdentifier>

Returns a reference to the vector of block references stored in block_refs.

• Returns: Reference to Vec<BlockIdentifier>.

• Usage Example:

  let references = cross_thread_ref_data.refs();
  

spawned_threads

pub fn spawned_threads(&self) -> Vec<ThreadIdentifier>

Identifies and returns a vector of thread identifiers that this block has spawned. It filters the threads from the threads_table to include only those threads which are marked as spawning from the current block.

• Returns: Vec<ThreadIdentifier> containing threads spawned by this block.

• Implementation Detail:
  Uses the rows() method of ThreadsTable to iterate over thread entries, then filters using is_spawning_block(&self.block_identifier) method on ThreadIdentifier.

• Usage Example:

  let new_threads = cross_thread_ref_data.spawned_threads();
  

Implementation Details

• Outbound messages and accounts stored in outbound_messages and outbound_accounts only contain data generated by the current block; data from previous blocks is excluded.

• The storing of outbound messages uses a HashMap keyed by AccountRouting with values as vectors of tuples pairing MessageIdentifier and a thread-safe reference-counted message wrapper (Arc<WrappedMessage>).

• There are commented-out methods (select_cross_thread_messages and select_cross_thread_accounts) hinting at planned or deprecated functionality for filtering messages and accounts based on user-provided predicates.

• The TODO comment in the code suggests potential optimization by possibly replacing message storage with a cell-like abstraction, implying future architectural revisions.

Interactions with Other Components

• Depends on types and modules such as:

  • MessageIdentifier and WrappedMessage from the message and repository modules for message handling.

  • WrappedAccount, AccountInbox, AccountRouting from the types::account and related submodules for account and routing data.

  • BlockIdentifier, BlockSeqNo, ThreadIdentifier, and ThreadsTable from types for uniquely identifying blocks, threads, and their relationships.

• The structure is likely used in coordinating state references across threads in a blockchain or distributed ledger system, where multiple threads process blocks independently but require synchronization on shared state references.

• The spawned_threads method facilitates dynamic thread management by identifying newly created threads from a block, which can be crucial for thread lifecycle management.

• Serialization and deserialization traits enable this data structure to be transmitted or stored persistently, supporting cross-thread communication or checkpointing.

Mermaid Diagram: Structure of CrossThreadRefData

classDiagram
class CrossThreadRefData {
-block_identifier: BlockIdentifier
-block_seq_no: BlockSeqNo
-block_thread_identifier: ThreadIdentifier
-outbound_messages: HashMap<AccountRouting, Vec<(MessageIdentifier, Arc<WrappedMessage>)>>
-outbound_accounts: HashMap<AccountRouting, (Option<WrappedAccount>, Option<AccountInbox>)>
-threads_table: ThreadsTable
-parent_block_identifier: BlockIdentifier
-block_refs: Vec<BlockIdentifier>
+as_reference_state_data()
+set_threads_table()
+set_block_refs()
+get_produced_threads_table()
+refs()
+spawned_threads()
}

This file is focused on managing and providing cross-thread block reference data within a system that handles concurrent thread-based block processing, enabling efficient referencing and synchronization of state across threads. For more on block identification, threading, and message handling, see the relevant topics such as Block Structure, Thread Management, and Message Passing.