Module torrust_tracker::shared::clock

source ·
Expand description

Time related functions and types.

It’s usually a good idea to control where the time comes from in an application so that it can be mocked for testing and it can be controlled in production so we get the intended behavior without relying on the specific time zone for the underlying system.

Clocks use the type DurationSinceUnixEpoch which is a std::time::Duration since the Unix Epoch (timestamp).

Local time:     lun 2023-03-27 16:12:00 WEST
Universal time: lun 2023-03-27 15:12:00 UTC
Time zone:      Atlantic/Canary (WEST, +0100)
Timestamp:      1679929914
Duration:       1679929914.10167426

NOTICE: internally the Duration is stores it’s main unit as seconds in a u64 and it will overflow in 584.9 billion years.

NOTICE: the timestamp does not depend on the time zone. That gives you the ability to use the clock regardless of the underlying system time zone configuration. See Unix time Wikipedia entry.

Modules

  • static_time
    It contains a static variable that is set to the time at which the application started.
  • time_extent
    It includes functionality to handle time extents.
  • utils
    It contains helper functions related to time.

Structs

  • Clock
    A generic structure that represents a clock.

Enums

Traits

  • StoppedTime
    Trait for types that can be used as a timestamp clock stopped at a given time.
  • Time
    Trait for types that can be used as a timestamp clock.
  • TimeNow
    Trait for types that can be manipulate the current time in order to get time in the future or in the past after or before a duration of time.

Functions

  • convert_from_datetime_utc_to_timestamp
    It converts a DateTime::<Utc> to a timestamp. For example, the DateTime::<Utc> of the Unix Epoch will be converted to a timestamp of 0: DurationSinceUnixEpoch::ZERO.
  • convert_from_iso_8601_to_timestamp
    It converts a string in ISO 8601 format to a timestamp. For example, the string 1970-01-01T00:00:00.000Z which is the Unix Epoch will be converted to a timestamp of 0: DurationSinceUnixEpoch::ZERO.
  • convert_from_timestamp_to_datetime_utc
    It converts a timestamp to a DateTime::<Utc>. For example, the timestamp of 0: DurationSinceUnixEpoch::ZERO will be converted to the DateTime::<Utc> of the Unix Epoch.

Type Definitions

  • Current
    The current clock. Defined at compilation time. It can be either the working clock (production) or the stopped clock (testing).
  • DurationSinceUnixEpoch
    Duration since the Unix Epoch.
  • Stopped
    The stopped clock. It returns always the same fixed time.
  • Working
    The working clock. It returns the current time.