Util Subsystem — Technical Summary

The src/util/ directory provides foundational infrastructure used across all of stellar-core. It covers timing, scheduling, logging, numeric safety, filesystem operations, serialization, data structures, threading, and various small helpers.

1. Virtual Clock & Timers (Timer.h, Timer.cpp)

VirtualClock

Central timing facility with two modes: REAL_TIME (wall clock) and VIRTUAL_TIME (simulated, for tests). Owns an asio::io_context for IO dispatch and a Scheduler for main-thread action scheduling.

• Key types: time_point (steady clock), system_time_point (wall/calendar time), duration.
• crank(bool block): The main event-loop step. Dispatches pending timers, polls IO (with exponential priority biasing under overload), runs scheduled actions, and transfers items from the thread-safe pending queue to the scheduler. In VIRTUAL_TIME mode, advances time to the next event if idle.
• postAction(): Thread-safe submission point for deferred work callbacks. Uses a mutex-protected pending queue; wakes the main thread via asio::post when enqueueing into an empty queue.
• setCurrentVirtualTime(): Advance virtual time forward (monotonic; asserts forward progress).
• sleep_for(): Real sleep in REAL_TIME, virtual time advance in VIRTUAL_TIME.
• shouldYield(): In REAL_TIME, returns true after 500ms has elapsed (time-slice limit). Always returns true in VIRTUAL_TIME.
• Time conversion helpers: to_time_t, from_time_t, systemPointToTm, tmToSystemPoint, isoStringToTm, tmToISOString, systemPointToISOString.