Skip to content

state.md

Latest commit

 

History

History
76 lines (45 loc) · 3.92 KB

state.md

File metadata and controls

76 lines (45 loc) · 3.92 KB
Raw

micro_svm.state

Overview

Summary

ProgramState encapsulates a concrete, non-symbolic state of a program, tracking global variables and intermediate object instances ("heap"). ObjectState and VariableState represent individual object and variable snapshots, respectively, with custom hashing for efficient full-state comparison and/or memoization.

Purpose

The micro_svm.state module and ProgramState in particular describes a (partial) program's state.

Role in the Project

The micro_svm.state module provides the fundamental data structures for representing and analyzing program states throughout the defect detection lifecycle. These structures serve as the foundation for:

  • Path validation: Verifying whether a sequence of instructions produces the (un)desired target state
  • State serialization: Persisting and restoring program states in JSON format

Contracts

  • Type consistency: ObjectState.type must be one of the container or structure type descriptors defined in types.py (ArrayTypeInfo, SetTypeInfo, MapTypeInfo, TransformTypeInfo, or StructureTypeInfo)
  • State compatibility: ObjectState.state must be compatible with the declared ObjectState.type - e.g., array types expect list of primitive values, map types expect list of pairs, structure types expect dictionary states
  • Reference handling: Object IDs in ProgramState.objects and ProgramState.expected_objects are string identifiers that must match; "expected" object ID should be present in the "objects" pool
  • Global variable references: Global variable values can be either null/0 or an object ID string, never a direct object state description

Classes

ObjectState: dataclass

Represents the complete state of a single object instance, including its type information and current field/container values.

Public API

  • Fields:
    • id: str - Unique identifier for this object instance, typically a string representation of a pointer/reference value
    • state: InitializerValueType - Current state value, which varies by type: list for arrays, list of pairs for maps, dictionary for structures, or a single value for primitives
    • type: ArrayTypeInfo | SetTypeInfo | MapTypeInfo | TransformTypeInfo | StructureTypeInfo - Type descriptor defining the structure, fields, and container properties of this object

Implementation details

ObjectState uses hash_str() function for computing hash values which implements simple Java-like hashing algorithm.

VariableState: dataclass

Represents the current value of a (global) variable in the program state, including its name and symbolic value.

Public API

  • Fields:
    • name: str - Global variable name
    • state: ValueType - Current symbolic value, which can be a primitive (integer, boolean, string, etc.) or a reference to an object ID

Implementation details

VariableState uses hash_str() function for computing hash values.

ProgramState: object

Represents the complete program state, encompassing global variables, all instantiated objects, and target state expectations.

Public API

  • Fields:
    • allow_object_reuse: bool - Flag controlling whether object instances can be reused across multiple locations (default: True)
    • expected_objects: dict[str, ObjectState] - Dictionary mapping top-level object IDs to their expected target states (values reference instances in objects pool)
    • global_variables: dict[str, VariableState] - Dictionary mapping global variable names to their current symbolic values
    • objects: dict[str, ObjectState] - Dictionary mapping all instantiated object IDs to their current states

Module-level functions

  • hash_str(s: str | object) -> int - Java-like string hashing function (basic h = 31 * h + ord(c) for each character)

AI usage disclosure: this document was generated by a large language model, all text has been validated and edited by a human developer.