mod.rs

Overview

This file defines the ThreadIdentifier struct, which provides a mechanism for uniquely identifying threads within the system. The uniqueness is guaranteed by combining a BlockIdentifier (representing a specific block in the blockchain) with a local u16 index. This design allows multiple threads to be spawned simultaneously from the same block without collisions in thread identifiers.

The file includes serialization and deserialization support, string formatting, and hashing implementations for ThreadIdentifier. It also defines conversions to and from byte arrays and hexadecimal strings, facilitating interoperability and storage.

ThreadIdentifier Struct

Definition

pub struct ThreadIdentifier([u8; 34]);

• Internally represented as a fixed-size 34-byte array.

• The first 2 bytes store a u16 thread index.

• The next 32 bytes store the associated BlockIdentifier.

Purpose

ThreadIdentifier acts as a unique handle for threads spawned from a specific blockchain block, ensuring no collisions by encoding both the block and a local thread index.

Derives and Traits

• Copy, Clone: Allows for inexpensive copying.

• Serialize, Deserialize: Supports (de)serialization with serde.

• Implements Default, From<[u8; 34]>, TryFrom<String>, LowerHex, Display, Debug, PartialEq, Eq, Hash, and AsRef<[u8]>.

Methods

new(block_id: &BlockIdentifier, id: u16) -> Self

Creates a new ThreadIdentifier by combining the given block_id and thread index id.

• Parameters:

  • block_id: Reference to a BlockIdentifier which the thread is spawned from.

  • id: A 16-bit unsigned integer representing the local thread index.

• Returns: A new ThreadIdentifier instance.

Usage example:

let block_id = BlockIdentifier::from(...);
let thread_id = ThreadIdentifier::new(&block_id, 1);

is_spawning_block(&self, block_id: &BlockIdentifier) -> bool

Checks if the thread was spawned by the given block.

• Parameters:

  • block_id: Reference to a BlockIdentifier to compare against the spawning block.

• Returns: true if the block_id matches the spawning block of this thread, false otherwise.

spawning_block_id(&self) -> BlockIdentifier

Retrieves the BlockIdentifier from which this thread was spawned.

• Returns: The associated BlockIdentifier.

Trait Implementations

• From<[u8; 34]> and From<ThreadIdentifier> for [u8; 34]
  Conversion between raw byte array and ThreadIdentifier.

• TryFrom<String>
  Attempts to decode a hex string into a ThreadIdentifier. Errors if the string is not a valid 34-byte hex-encoded array.

• LowerHex
  Formats the identifier as a lowercase hexadecimal string.

• Display
  Formats the identifier as <T:hex_string>, where hex_string is the hex representation of the internal byte array.

• Debug
  Formats the identifier as ThreadIdentifier<hex_string>.

• AsRef<[u8]>
  Allows borrowing the internal byte array.

• PartialEq, Eq
  Equality based on the internal byte array content.

• Hash
  Hashes the internal byte array, enabling use as a key in hash maps.

Implementation Details and Notes

• The first 2 bytes of the internal array store the thread index, encoded in big-endian order.

• The remaining 32 bytes store the block identifier bytes.

• The serde_with::Bytes attribute ensures that the 34-byte array is serialized as bytes rather than a sequence of numbers.

• The TryFrom<String> implementation uses hex::decode to convert from a hex-encoded string and validates length.

• Equality, hashing, and ordering are based on the raw byte array, ensuring consistent behavior.

• The file references a BlockIdentifier type from crate::types::BlockIdentifier.

• The ord submodule is declared but not detailed here.

• Comments explain the motivation for using a combined block ID and u16 index instead of just u16 to guarantee uniqueness across threads.

Interaction with Other Parts of the System

• Uses BlockIdentifier to tie thread identifiers to specific blockchain blocks.

• The ord submodule may provide ordering or comparison utilities related to threads, but it is not detailed in this file.

• Serialization and deserialization support facilitates network communication or persistent storage of thread identifiers.

• Integration with hexadecimal encoding/decoding enables human-readable representations and parsing in logs or external interfaces.

Diagram

classDiagram
class ThreadIdentifier {
-[u8; 34] data
+new(block_id: &BlockIdentifier, id: u16): Self
+is_spawning_block(block_id: &BlockIdentifier): bool
+spawning_block_id(): BlockIdentifier
+as_ref(): &[u8]
<<trait>> Serialize
<<trait>> Deserialize
<<trait>> Copy
<<trait>> Clone
<<trait>> Default
<<trait>> From<[u8;34]>
<<trait>> TryFrom<String>
<<trait>> LowerHex
<<trait>> Display
<<trait>> Debug
<<trait>> PartialEq
<<trait>> Eq
<<trait>> Hash
}
ThreadIdentifier --> BlockIdentifier : contains

This diagram shows the ThreadIdentifier struct, its core data, primary methods, and the traits implemented, as well as its composition relationship with BlockIdentifier.