validations.rs

Overview

This file defines additional validation and configuration adjustment methods for the Config struct, which is imported from the parent module. These methods ensure that the system configuration meets certain runtime requirements related to CPU core availability and execution timeouts. The primary functionalities provided are:

• Verifying that the number of CPU cores available on the host machine meets a specified minimum.

• Adjusting and validating execution timeout parameters to maintain logical and safe timing relationships between block and transaction production and verification.

These validations are critical in maintaining the performance and correctness constraints of the system's runtime environment.

Config Implementation Extensions

ensure_min_cpu

pub fn ensure_min_cpu(mut self, min_number_of_cores: usize) -> Self

• Purpose:
  Validates that the machine's available CPU cores are at least the specified minimum. If the condition is met, it sets the parallelization_level in the local configuration to the total number of CPU cores detected.

• Parameters:

  • min_number_of_cores: usize — The minimum required number of CPU cores.

• Returns:

  • Self — The updated Config instance with the parallelization_level adjusted.

• Behavior:

  • Uses the num_cpus::get() function to determine the total number of CPU cores.

  • Logs the detected CPU core count at trace level.

  • Asserts that the detected count is not less than the minimum required; panics otherwise.

  • Sets the local.parallelization_level to the detected CPU core count.

  • Returns the updated Config.

• Usage Example:

let config = Config::default()
    .ensure_min_cpu(4);

This example ensures that the runtime environment has at least 4 CPU cores and sets the parallelization level accordingly.

ensure_execution_timeouts

pub fn ensure_execution_timeouts(mut self) -> Self

• Purpose:
  Validates and adjusts execution timeout parameters to ensure consistent and safe timing relationships are maintained between block and transaction production and verification.

• Parameters:
  None.

• Returns:

  • Self — The updated Config instance with potentially adjusted timeout values.

• Behavior:

  • Retrieves time_to_produce_block_millis and uses it as the baseline.

  • Checks if time_to_produce_transaction_millis is set:

    • If set, asserts it does not exceed the block production time.

    • If not set, assigns it the block production time value.

  • Asserts that time_to_verify_block_millis is at least as large as time_to_produce_block_millis.

  • Verifies or sets time_to_verify_transaction_millis:

    • If set, asserts it does not exceed the block verification time.

    • If not set, assigns it the block verification time.

  • Checks or sets time_to_verify_transaction_aborted_with_execution_timeout_millis:

    • If set, asserts it does not exceed the transaction production time.

    • If not set, assigns it to 90% of the transaction production timeout (rounded up).

  • Returns the updated Config.

• Important Validation Rules:

  • Transaction production timeout ≤ Block production timeout.

  • Block verification timeout ≥ Block production timeout.

  • Transaction verification timeout ≤ Block verification timeout.

  • Aborted transaction execution timeout ≤ Transaction production timeout.

• Usage Example:

let config = Config::default()
    .ensure_execution_timeouts();

This example verifies and sets the execution timeout parameters to consistent values based on the block and transaction timings.

Implementation Details and Algorithms

• The methods use assertion checks (assert!) to enforce critical constraints, which will cause a panic if violated. This ensures that misconfigured runtime parameters are caught early.

• The use of optional timeout fields (Option<u64>) allows the system to fill in defaults where values are missing, promoting safer and more predictable behavior.

• The multiplication by 0.9 and ceil function in ensure_execution_timeouts for aborted transaction timeout introduces a safety margin by setting it slightly less than the standard transaction timeout.

• The tracing::trace! macro calls provide internal logging for debugging and monitoring the configuration validation process.

Interaction with Other System Components

• The Config struct, which these methods extend, is central to the system's runtime configuration and is likely defined in the parent module.

• The CPU core count retrieval depends on the external crate num_cpus.

• Logging is handled via the tracing crate, a common Rust instrumentation library.

• These validation methods are intended to be called during configuration setup or initialization phases, ensuring that downstream components receive a validated and consistent configuration.

• The fields adjusted (local.parallelization_level and global timeout fields) presumably influence parallel execution and timeout handling in the system's execution engine or scheduler.

Visual Diagram

classDiagram
class Config {
+ensure_min_cpu()
+ensure_execution_timeouts()
-local.parallelization_level
-global.time_to_produce_block_millis
-global.time_to_produce_transaction_millis
-global.time_to_verify_block_millis
-global.time_to_verify_transaction_millis
-global.time_to_verify_transaction_aborted_with_execution_timeout_millis
}
Config : uses num_cpus crate
Config : uses tracing crate