Time Overview

Components on Fuchsia can read current time using three different time standards:

  • Monotonic: Monotonic time is a measurement of the time since the system was powered on. 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.
  • 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. Monotonic time has the fewest failure modes and the most stable behavior so should generally be the default choice unless there is a reason that monotonic time will not work. UTC has fewer failure modes and more stable behavior than local time so should be preferred over local time unless there is some reason that local time is necessary.

For example:

  1. 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.
  2. 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.
  3. 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.
  4. 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.