Crate matrix_sdk_base::ruma::time

Description

Complete drop-in replacement for std::time that works in browsers.

Currently Instant::now() and SystemTime::now() will simply panic when using the wasm32-unknown-unknown target. This implementation uses Performance.now() for Instant and Date.now() for SystemTime to offer a drop-in replacement that works in browsers.

At the same time the library will simply re-export std::time when not using the wasm32-unknown-unknown target and will not pull in any dependencies.

Additionally, if compiled with target-feature = "atomics" it will synchronize the timestamps to account for different context’s, like web workers. See Performance.timeOrigin for more information.

Using -Ctarget-feature=+nontrapping-fptoint will improve the performance of Instant::now() and SystemTime::now(), but the vast majority of the time is still spent going through JS.

Target

This library specifically targets browsers, that support Performance.now(), with the wasm32-unknown-unknown target. Emscripten is not supported. WASI doesn’t require support as it has it’s own native API to deal with std::time.

Furthermore it depends on wasm-bindgen, which is required. This library will continue to depend on it until a viable alternative presents itself, in which case multiple ecosystems could be supported.

Note

Ticking during sleep

Currently a known bug is affecting browsers on operating system other then Windows. This bug prevents Instant from continuing to tick when the context is asleep. This doesn’t necessarily conflict with Rusts requirements of Instant, but might still be unexpected.

See the MDN documentation on this for more information.

Context support

The implementation of Instant::now() relies on the availability of the Performance object, a lack thereof will cause a panic. This can happen if called from a worklet.

Usage

You can simply import the types you need:

use web_time::{Instant, SystemTime};

let now = Instant::now();
let time = SystemTime::now();

Features

serde

Implements serde::Deserialize and serde::Serialize for SystemTime.

MSRV

As this library heavily relies on wasm-bindgen the MSRV depends on it. At the point of time this was written the MSRV is 1.60.

Alternatives

instant is a popular alternative! However the API it implements doesn’t match std::time exactly.

Contributing

See the CONTRIBUTING file for details.

Attribution

Inspiration was taken from the instant project.

Additional insight was taken from the time project.

Changelog

See the CHANGELOG file for details.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Copyright

A majority of the code and documentation was taken from std::time. For license information see #License.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Structs

• Duration
  A Duration type to represent a span of time, typically used for system timeouts.
• Instant
  A measurement of a monotonically nondecreasing clock. Opaque and useful only with Duration.
• SystemTime
  A measurement of the system clock, useful for talking to external entities like the file system or other processes.
• SystemTimeError
  An error returned from the duration_since and elapsed methods on SystemTime, used to learn how far in the opposite direction a system time lies.
• TryFromFloatSecsError
  An error which can be returned when converting a floating-point value of seconds into a Duration.

Constants

• UNIX_EPOCH
  An anchor in time which can be used to create new SystemTime instances or learn about where in time a SystemTime lies.