Components on Fuchsia can read current time using four different time standards:
- Monotonic: Monotonic time is a measurement of the time since the system was powered on, not including time spent in Suspend-to-Idle. Monotonic time always moves forwards and is always available to all applications but is only meaningful with the context of a single power cycle on a single Fuchsia device.
- Boot: Boot time is a measurement of the time since the system was powered on including any time spent in Suspend-to-Idle. Like monotonic time, boot time always moves forward, is always available, and is only meaningful with the context of a single power cycle on a single Fuchsia device.
- UTC: UTC time is the system’s best estimate of Coordinated Universal Time. UTC is usually acquired over a network so there are conditions under which the system may not know UTC. Developers using UTC should pay particular attention to UTC behavior to understand the unique properties of UTC on Fuchsia.
- Local: Local time is the system’s best estimate of the standard time at the device’s location, aka "wall clock time". Local time is derived from UTC and time zone, so inherits much of the UTC behavior. There are conditions under which local time is not available. The local time will jump substantially if the user changes time zone.
These time standards are frequently available through the time functions in supported languages in addition to time syscalls.
As a developer, you must select the most appropriate time standard to address each problem. We recommend using monotonic time unless your program needs to be aware of time spent in Suspend-To-Idle. Boot time is recommended if timestamps must be kept in sync with underlying hardware or external services, and monotonicity is required. UTC can be used if timestamps must be correlated with external services and monotonicity is not required. Local time, as a derivative of UTC time, is generally only used in UX applications.
For example:
- Use monotonic time to implement a ten second delay between retries. Monotonic time will be available in all cases so provides the simplest and most reliable solution.
- Use boot time to timestamp trace points in Fuchsia, as traces should display time spent suspended and cannot have their timeline jump back and forth.
- Use UTC time to expire and delete a file stored on disk after seven days. Here monotonic time would not allow the expiry time to be preserved across power cycles and local time would have coupled the correctness of the expiry to the timezone setting.
- Use UTC time to timestamp an on-device event that will be read by some server. In this case monotonic time would not work since the server probably does not know when the Fuchsia device last powered on. Using local time would require that the device and server agree on the timezone, which would be error prone.
- Use local time to display the current time to the user as an analog clock face. Local time is most natural time standard for users so no other time standards are practical here.
Testing code that depends on time can be difficult on any platform. Tools and best practices for testing time dependencies on Fuchsia are being developed and will be linked here when available.