Architecture and Internal Design

This page explains how cPerformanceManager is structured internally and why it is designed the way it is.

The class is more than a thin timer wrapper. It is a session-bound timing and execution-control component with:

• multiple timing backends
• validation-aware elapsed-time reads
• optional Excel environment suppression
• diagnostic surfaces
• explicit cleanup behavior
• structured checkpoint / report state

Design goals

The class is designed around a few core goals:

1. Provide a single public timing interface over multiple timing backends.
2. Enforce session integrity so start and elapsed reads stay method-consistent.
3. Expose both numeric and human-readable elapsed-time outputs.
4. Support Excel environment control through shared TW management.
5. Keep cleanup explicit and deterministic.
6. Support structured checkpoint capture and export within a timing session.
7. Preserve sufficient internal visibility for diagnostics and regression testing.

High-level architecture

At a high level, the class is organized into these internal layers:

• Lifecycle
• Core timing API
• Session / state inspection
• Diagnostics / benchmark helpers
• Execution control / environment
• Shared time-waster control
• Checkpoints / structured reporting
• Session / validation helpers
• Timing source helpers
• Timing capture / alignment helpers
• Checkpoint / report helper routines

Why the class is stateful

The class could have been designed as a looser stateless wrapper around timing calls, but it was intentionally not built that way.

A stateful design makes it possible to support:

• session binding
• validation-aware elapsed reads
• internal diagnostics
• cache / inspection exposure
• deterministic environment cleanup
• per-instance TW participation tracking
• structured checkpoint accumulation
• per-session run labels and report export

Why the public surface mixes timing and execution control

The class combines:

• timing
• environment suppression
• pause helpers
• diagnostics
• checkpoint/reporting

This is deliberate. It is not just a raw timer. It is a performance manager for benchmark-oriented and performance-aware VBA workflows.

Structured reporting layer

A newer internal layer stores checkpoint rows captured during the current session.

Each checkpoint row stores:

• sequence number
• checkpoint name
• optional note
• delta seconds
• cumulative seconds
• method metadata
• optional run label

This reporting layer allows the class to provide both:

• a machine-readable export (ReportAsArray)
• a human-readable export (ReportAsText)

without pushing that responsibility into every caller.