---
title: CodeTimerEntry
summary: API reference for CodeTimerEntry.
status: draft
owner: <owner>
last_reviewed: 2026-07-23
library: SAIF.Framework.CodeTimer
reference_type: package
---

# CodeTimerEntry

`CodeTimerEntry` is the mutable record of one timer's running state: name, quantity, start/stop timestamps, longest/shortest/elapsed durations, and a history of captured [CustomTimeSpan](CustomTimeSpan.md) instances. Instances are held in [CodeTimer](CodeTimer.md)'s static timer dictionary.

## Purpose
- Track the lifecycle (running/not running) and accumulated statistics of a single named or method-scoped timer.

## Context
- Namespace: `SAIF.Framework.CodeTimer`
- Assembly/package: `SAIF.Framework.CodeTimer.dll`

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| name | `public string name` | The hierarchical key/name identifying this timer entry. |
| quantity | `public int quantity` | Number of times this timer has been started; initialized to `1` on construction. |
| started | `public DateTime started` | Timestamp when the entry was first created. |
| lastStarted | `public DateTime lastStarted` | Timestamp of the most recent `Start()` call. |
| lastStopped | `public DateTime lastStopped` | Timestamp of the most recent `Stop()` call. |
| longest | `public double longest` | Longest single recorded span, in milliseconds. |
| shortest | `public double shortest` | Shortest single recorded span, in milliseconds (`-1` until a span is recorded). |
| elapsed | `public double elapsed` | Cumulative elapsed time across all recorded spans, in milliseconds. |
| spans | `public List<CustomTimeSpan> spans` | History of individual captured [CustomTimeSpan](CustomTimeSpan.md) instances for this entry. |
| CodeTimerEntry | `public CodeTimerEntry(string name)` | Constructs a new entry, marking it started with `quantity = 1`. |
| IsRunning | `public bool IsRunning()` | Returns whether the entry is currently in a running state. |

## Inherited public members

<!-- Omitted: CodeTimerEntry does not derive from any base class in a documented dependency; it inherits only from System.Object. -->

## Behavioral notes
- `Start()` and `Stop()`/`Stop(bool isFinal)` are declared `internal`, so timer lifecycle control is restricted to within the `SAIF.Framework.CodeTimer` assembly; only `CodeTimer` (in the same assembly) can start/stop an entry directly.
- Calling `Start()` while already running throws `ApplicationException("StopWatch running")` (see [BR-001](../../business-rules.md#br-001-a-timer-must-not-be-started-while-already-running)).
- Calling `Stop(bool)` while not running throws `ApplicationException("StopWatch not running")` (see [BR-002](../../business-rules.md#br-002-a-timer-must-not-be-stopped-while-not-running)).
- On `Stop(bool isFinal)`, the entry computes the elapsed span since `lastStarted`, adds it to cumulative `elapsed`, updates `longest`/`shortest`, and appends a new `CustomTimeSpan` to `spans`.
- A commented-out `Stopwatch sw` field exists in source but is not active; timing is instead computed from `DateTime` timestamp differences*.

## Constraints and usage notes
- Instances are only meaningfully constructed and mutated by `CodeTimer`; external callers can read the public fields but cannot call `Start()`/`Stop()` directly since those members are `internal`.
- `shortest` is `-1` until the first `Stop()` call completes, so callers should not treat `-1` as a valid duration.

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- SAIF.Framework.CodeTimer\SAIF.Framework.CodeTimer\CodeTimerEntry.cs