Repository navigation
VirtLang v3.3.0
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 (
debuggerpackage):- 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.Snapshotstruct has been introduced, containing aCallStackand a deep copy of theenvironment.Environment. - The
Debuggernow maintains a list ofSnapshotstaken 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.
- A new
- Current Snapshot Triggers: Snapshots are automatically taken by the evaluator:
- Just before a function or constructor call unwinds due to an error (including explicit
returnstatements that might be part of an error propagation). - If the main program evaluation terminates due to an unhandled error.
- Just before a function or constructor call unwinds due to an error (including explicit
- 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 (
environmentpackage):- 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 withinRuntimeValue). This is crucial for the integrity of debugger snapshots.
- A new
- Evaluator Integration for Snapshots:
- The evaluator now calls
debugger.TakeSnapshot()at strategic points when errors are encountered (specifically inevalCallExprandevalProgramupon error conditions), preserving the state just before error propagation or termination.
- The evaluator now calls
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.Snapshotsfield for consumption by host environments. - The
Debuggerstruct now includes aSnapshots []Snapshotfield.
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.Snapshotsto 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!