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][libc] 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][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][fuchsia-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][zx-monotonic] for more details.
- {C }
Monotonic time is accessible through [libzircon][c-libzircon].
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/c/main.c" region_tag="common_imports" adjust_indentation="auto" %}
{% 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][cpp-libzx].
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/cpp/main.cc" region_tag="common_imports" adjust_indentation="auto" %}
{% 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][rust-zircon] crate. This crate is only available in-tree.
{% 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][c-libzircon].
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/c/main.c" region_tag="common_imports" adjust_indentation="auto" %}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/c/main.c" region_tag="utc_imports" adjust_indentation="auto" %}
{% 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][cpp-libzx].
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/cpp/main.cc" region_tag="common_imports" adjust_indentation="auto" %}
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/cpp/main.cc" region_tag="utc_imports" adjust_indentation="auto" %}
{% 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][rust-runtime] crate and use the syscall wrappers in the [fuchsia_zircon][rust-zircon] crate. The [fuchsia_async][rust-async] crate contains utilities to aid waiting for the clock to start. Note that these crates are only available in-tree.
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/time/rust/src/main.rs" region_tag="utc" adjust_indentation="auto" %}
libc[c-clock-gettime]: https://linux.die.net/man/3/clock_gettime
fuchsia-utc-behavior /reference/syscalls/clock_get_monotonic.md c-libzircon /concepts/process/core_libraries.md#libzx rust-runtimerust-zirconrust-async