Simulator Main Loop

Common to time simulations, the Linden simulators have a main loop where time deltas occur and state changes and housekeeping tasks are organized. Most of this is simply hidden from view and is experienced as either "laggy today" or "not too laggy today." Some phases of the loop are reported back to the Viewer and displayed on the Statistics floater and are the subject of much interest and debate. So here is a high-level breakdown of the loop and a description that relates simulation back to the Statistics floater.
== Columns ==
=== App State ===
The Simulator, like the Viewer, defines numerous application states which serve as an internal marker of progress of context while executing. Labels are mostly self-describing and occur once but there are exceptions. The 'SVC_PUMP_*' and 'SVC_CB_*' labels mark repetitions of the same I/O logic at four different points in a single pass through the loop.
=== Operations ===
Each state is broken down, where possible, into discrete steps tagged with function and method names, some real, some imaginary.
=== Bounds ===
A simulation frame does not execute every possible step on every frame. Bounding of execution load is performed in several ways to avoid unnecessary computation and improve overall framerate behavior. These bounds take several forms.
Frequency bound. This indicates how often the step is invoked. As indicated by the key, there are roughly four schemes in play:
* Every frame (green). The most common case, the step is invoked on every frame.
* Skipped frames (yellow). Invoked on every Nth frame of simulation.
* Scheduled on the clock (pink). Invoked after a time interval has passed.
* Selectively run based on random logic (red). Complex or opaque skipping logic is applied.
Time bound. Once started, a simulation step does not always run to completion. Early exit from the step may be performed to get on with the frame or as a result of not-yet-arrived data. Breakdown:
* Run to completion (green).
* Run to a clock target (yellow). Usually something more complicated than a simple deadline but the idea is to limit damage to the frametime.
* Run to complex time target (pink). Rococo schemes for early termination.
* Run to simple clock target (red). Basic deadline stop.
Other bounds. Other system state can lead to early termination of a step. This can literally be anything but we have a few 'common' cases:
* No other bound (green).
* Run until HTTP request throttles invokes (yellow). Back off the HTTP when using it too hard.
* Run until agent limits hit (pink). Simulation step has a related agent limit controlling execution.
* Run until random logic fires (red). Some complex case allowing early termination of step.
=== Viewer Statistics ===
The remaining column involves the reporting of loop statistics to interested viewers. Metrics collection in the simulator is mostly used for internal processes and is kept there. But the SimStats message, used to populate the Statistics floater, communicates some of these back to the Viewer. These are indicated by green bars in the four reporting columns which are also tagged with the text from the Statistics floater.
There are gaps in the simulation frame that aren't reported to the Viewer. These are indicated in yellow and are simply gathered internally. There are also some additional metrics being reported to the Viewer that aren't on the Statistics floater. (Something to be documented in the future.)
Finally, the 'Physics Step' and 'Physics Other' spans aren't precisely as indicated. They're collected somewhat independently as part of Havok simulation but this will do for representational purposes.