Time language support

This page details how you can handle time when developing software on Fuchsia.

In general, you may use any time library available for your language. Most libraries are able to link against Fuchsia’s libc implementation to obtain time. It is recommended that you use a platform-agnostic library unless you need Fuchsia specific time operations.

Various time options are available, such as:

Language Monotonic UTC
C clock_gettime{:.external} time{:.external}
C++ std::chrono::steady_clock{:.external} std::chrono::system_clock{:.external}
Rust std::time::Instant{:.external} std::time::SystemTime{:.external}

Fuchsia specific time operations

In some cases, you will need to handle time in a Fuchsia specific manner. This is necessary when you need to handle Fuchsia’s representation of time directly, or when you need to handle Fuchsia specific UTC behavior.

Monotonic time

Monotonic time on Fuchsia is represented as a signed 64 bit integer, which contains the number of nanoseconds since the system was powered on. See zx_clock_get_monotonic for more details.

  • {C }

    Monotonic time is accessible through libzircon.

    1. {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/c/main.c" region_tag="common_imports" adjust_indentation="auto" %}
    3. {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/c/main.c" region_tag="monotonic" adjust_indentation="auto" %}

  • {C++}

    Monotonic time is accessible through libzx.

    1. {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/cpp/main.cc" region_tag="common_imports" adjust_indentation="auto" %}
    3. {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/cpp/main.cc" region_tag="monotonic" adjust_indentation="auto" %}

  • {Rust}

    Monotonic time is accessible through the fuchsia_zircon crate. This crate is only available in-tree.

    1. {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/rust/src/main.rs" region_tag="monotonic" adjust_indentation="auto" %}

UTC time

UTC time on Fuchsia is represented as a signed 64 bit integer that contains the number of nanoseconds since the Unix epoch (January 1st, 1970).

Operations on the UTC clock require obtaining a handle to the UTC clock provided to the runtime.

Handling the UTC clock directly enables a few Fuchsia specific operations, including:

  • Inspecting the UTC clock’s properties.

  • Waiting for the UTC clock to begin running, which indicates it has been synchronized, before reading it.

  • {C }

    You can obtain a handle to the UTC clock using zx_utc_reference_get and use the syscalls exposed in libzircon.

    1. {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/c/main.c" region_tag="common_imports" adjust_indentation="auto" %}
    2. {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/c/main.c" region_tag="utc_imports" adjust_indentation="auto" %}
    4. {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/c/main.c" region_tag="utc" adjust_indentation="auto" %}

  • {C++}

    You can obtain a handle to the UTC clock using zx_utc_reference_get and use the syscall wrappers in libzx.

    1. {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/cpp/main.cc" region_tag="common_imports" adjust_indentation="auto" %}
    2. {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/cpp/main.cc" region_tag="utc_imports" adjust_indentation="auto" %}
    4. {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/cpp/main.cc" region_tag="utc" adjust_indentation="auto" %}

  • {Rust}

    You can obtain a handle to the UTC clock using the fuchsia_runtime crate and use the syscall wrappers in the fuchsia_zircon crate. The fuchsia_async crate contains utilities to aid waiting for the clock to start. Note that these crates are only available in-tree.

    1. {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/rust/src/main.rs" region_tag="utc" adjust_indentation="auto" %}