Skip to content

Start a timed operation

This operation opens a new timing window for a method, or resumes one that was previously started, and returns the hierarchical key that a matching Stop call will need later. It is the entry point that lets a caller build nested timer paths — a parent operation's key can be threaded into child calls so the resulting report shows one operation's timing nested inside another's.

Field Value
Operation ID CT-OP-001
Trigger Caller invokes CodeTimer.Start(MethodBase...)
Inputs MethodBase method, optional customName, optional parentTimerKey
Outputs Timer key string; new or resumed CodeTimerEntry state when timing is allowed
Primary components CodeTimer.Start, CodeTimer.GetCodeTimerParent, CodeTimerEntry.Start, CodeTimerEntry.CodeTimerEntry
Entry point SAIF.Framework.CodeTimer\SAIF.Framework.CodeTimer\CodeTimer.cs

Steps

  1. Derive the base timer name from method.Name, appending .{customName} whenever the caller supplied a custom suffix, so that two calls to the same method under different names produce distinct timer entries.
  2. Inspect the target method for a CodeTimerAttribute via reflection — this is the per-method gate that decides whether the method participates in timing at all.
  3. If the method carries no CodeTimerAttribute, return the incoming parentTimerKey unchanged and make no changes to the timer store (BR-005).
  4. If the attribute is present but its Enabled flag is false, return the incoming parentTimerKey unchanged, again without touching the store (BR-005).
  5. Assemble the hierarchical timer key via GetCodeTimerParent, inserting a ; separator only when a non-empty parent key was supplied — this is what turns a flat name into a parent;child path that later reporting steps can split back apart.
  6. Evaluate the global CodeTimer.Enabled switch, the second and coarser-grained gate.
  7. If the switch is false, return an empty string and skip every state change, regardless of what the per-method attribute allowed (BR-005).
  8. Look up the composite key in the static data dictionary that backs the entire timer store.
  9. If no entry exists yet for that key, create a new CodeTimerEntry; its constructor stamps both started and lastStarted with DateTime.Now, sets the initial quantity to 1, and marks the entry as running.
  10. If an entry already exists for that key, call CodeTimerEntry.Start() to resume it rather than replacing it, which preserves prior accumulated statistics across repeated start/stop cycles for the same key.
    • On failure: if the entry is already marked running, CodeTimerEntry.Start() refuses the duplicate start and throws instead of silently restarting the clock (BR-001).
  11. Return the composite key to the caller. This value has no further use for the caller other than being passed back in as parentTimerKey on a nested Start call, or reused to address the same entry on the matching Stop call.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Start request]) --> Resolve[Resolve method and custom name]
    Resolve --> Attr{Attribute present<br>and enabled?}
    Attr -->|No| NoOp([Return parent key])
    Attr -->|Yes| BuildKey[Build hierarchical key]
    BuildKey --> Enabled{CodeTimer.Enabled?}
    Enabled -->|No| Disabled([Return empty string])
    Enabled -->|Yes| Exists{Entry already exists?}
    Exists -->|No| Create[Create CodeTimerEntry]
    Exists -->|Yes| Resume[Resume existing entry]
    Create --> EndOk([Return timer key])
    Resume --> EndOk

Failure and edge-case behavior

  • A method with no CodeTimerAttribute produces no timer entry at all; the call is a pass-through that simply hands back the incoming parent key.
  • When the global timer subsystem is disabled, Start returns an empty string rather than a usable key, so callers should not assume a non-empty key is always returned (BR-005).
  • Calling Start again for a key that is already running — for example, a re-entrant or recursive call that was not designed to nest — throws under BR-001 rather than extending the existing timing window.

Sources

  • SAIF.Framework.CodeTimer\SAIF.Framework.CodeTimer\CodeTimer.cs
  • SAIF.Framework.CodeTimer\SAIF.Framework.CodeTimer\CodeTimerAttribute.cs
  • SAIF.Framework.CodeTimer\SAIF.Framework.CodeTimer\CodeTimerEntry.cs