Skip to content

VirtLang v3.3.0

Choose a tag to compare

@dev-kas dev-kas released this 21 May 08:30
· 46 commits to master since this release

VirtLang-Go v3.3.0 Release Notes: Introducing Debugger Snapshots for Enhanced Diagnostics

We are pleased to announce the release of VirtLang-Go v3.3.0! This version further enhances our powerful debugging engine by introducing Debugger Snapshots, a feature designed to provide deep insights into program state, especially for post-mortem analysis of errors.

Building on the advanced stepping and call stack tracking from v3.2.0, snapshots allow the debugging engine to capture the complete state (call stack and environment) at critical moments, such as just before an error unwinds the execution flow.

Major Features & Enhancements

  • Debugger Snapshots (debugger package):
    • Benefit: Enables powerful post-mortem debugging and historical state analysis by capturing the program's call stack and variable environment at specific points. This is invaluable for understanding the conditions leading up to runtime errors.
    • Details:
      • A new debugger.Snapshot struct has been introduced, containing a CallStack and a deep copy of the environment.Environment.
      • The Debugger now maintains a list of Snapshots taken during execution.
      • A debugger.TakeSnapshot() method allows the engine to capture the current execution state.
      • Deep Copying: To ensure snapshot integrity, both the call stack and the environment (including variables and their values) are deep-copied when a snapshot is taken. This means subsequent changes to the live program state will not affect previously captured snapshots.
    • Current Snapshot Triggers: Snapshots are automatically taken by the evaluator:
      • Just before a function or constructor call unwinds due to an error (including explicit return statements that might be part of an error propagation).
      • If the main program evaluation terminates due to an unhandled error.
    • Host Environment (e.g., Xel) Integration: Host environments can access these snapshots to provide users with a historical view of program states, aiding in diagnosing complex issues.

Core Interpreter Enhancements

  • Environment Deep Copying (environment package):
    • A new environment.DeepCopy() helper function has been implemented. This function meticulously creates a full, independent copy of an environment, including its parent chain and all variables (handling nested objects and arrays within RuntimeValue). This is crucial for the integrity of debugger snapshots.
  • Evaluator Integration for Snapshots:
    • The evaluator now calls debugger.TakeSnapshot() at strategic points when errors are encountered (specifically in evalCallExpr and evalProgram upon error conditions), preserving the state just before error propagation or termination.

API Changes (for Go Consumers)

  • No direct breaking changes to the existing public API for this specific feature set. The snapshotting mechanism is primarily an internal enhancement to the debugger's capabilities, exposed via the Debugger.Snapshots field for consumption by host environments.
  • The Debugger struct now includes a Snapshots []Snapshot field.

Testing

  • Added new unit tests (debugger/snapshot_test.go) specifically for the snapshotting feature, verifying:
    • Correct capture of call stack and environment data in snapshots.
    • The integrity of deep copies, ensuring that live state modifications do not alter captured snapshot data.
  • These tests confirm the reliability of the snapshot mechanism.

Known Issues and Limitations

  • Snapshot Management: The current implementation collects snapshots without a limit. Host environments (like Xel) will be responsible for managing snapshot storage, display, and potential limits to control memory usage for long-running or error-prone sessions.
  • Scope of Snapshotting: Snapshots are currently triggered automatically on certain error conditions. User-initiated snapshots or snapshots at every step/breakpoint are not yet engine-level features but could be orchestrated by a host environment.

Upgrade Notes

  • This release adds a significant diagnostic capability to the VirtLang-Go debugger engine.
  • The changes are backwards-compatible for VirtLang-Go language users and for most Go consumers of the existing debugger API (v3.2.0).
  • Go applications acting as debugger hosts (like Xel) can now access Debugger.Snapshots to provide enhanced debugging UIs.

Getting Started

Refer to the README.md and the updated DOCS.md for information on how to use the interpreter and its debugging features. The DOCS.md has been updated to include the new snapshot-related types.

Acknowledgements

Continued thanks to @dev-kas for pushing the boundaries of VirtLang-Go's debugging capabilities with this advanced snapshotting feature!