Module Affect_unix.Ptime

POSIX time.

This time is measured by sampling this clock.

Warning. POSIX time does not increase monotonically, it is subject to operating system calendar time adjustements and can even go back in time. Use Mtime if you want to wait for wall-clock time spans.

Note. This is a minimal version of the ptime library which has more tools to deal with POSIX timestamp (e.g. date-time values) with the same representation, head there for more.

type t

The type for picosecond precision POSIX timestamps in the range [min_stamp;max_stamp]. Note that POSIX timestamps, and hence values of this type are by definition always on the UTC timeline.

Waiting

Warning. This relies on an Unix.unblocker being setup on the executing domain.

val wait_until : t -> unit

wait_until t waits until the POSIX clock can be caught being greater or equal to the timestamp t. The actual supported resolution is unspecified and may also depend on scheduling but POSIX millisecond precision should be supported. Use observe_wait_until to measure the overshoot.

val observe_wait_until : t -> t

observe_wait_until is like wait_until but returns the value of the POSIX clock when the function returns.

Actions

val wait_until' : t -> 'tag -> 'tag Affect.Action.t

wait_until' t tag is the action for wait_until. The action invocation enables and synchronizes with tag when the POSIX clock can be caught to be greater or equal to the timestamp t.

POSIX spans

module Span : sig ... end

POSIX time spans.

Timestamps

val now : unit -> t

now () is the current value of the POSIX clock.

val epoch : t

epoch is 1970-01-01 00:00:00 UTC.

val min_stamp : t

min_stamp is 0000-01-01 00:00:00 UTC, the earliest timestamp representable.

val max_stamp : t

max_stamp is 9999-12-31 23:59:59.999999999999 UTC, the latest timestamp representable.

Predicates

val equal : t -> t -> bool

equal t0 t1 is true if and only if t0 and t1 are the same timestamps.

val compare : t -> t -> int

compare t0 t1 is a total order on timestamps that is compatible with timeline order.

val is_earlier : t -> than:t -> bool

is_earlier t ~than is true if and only if compare t than = -1.

val is_later : t -> than:t -> bool

is_later t ~than is true if and only if compare t than = 1.

Arithmetic

WARNING. A POSIX time span is not equal to an SI second based time span. Do not use these functions to perform calendar arithmetic or measure wall-clock durations, you will fail.

val diff : t -> t -> Span.t

diff t t' is the signed POSIX span t - t' that happens between the timestamps t and t'.

val add_span : t -> Span.t -> t option

add_span t d is timestamp t + d, that is t with the signed POSIX span d added. None is returned if the result is not in the range [min_stamp;max_stamp].

val sub_span : t -> Span.t -> t option

sub_span t d is the timestamp t - d, that is t with the signed POSIX span d subtracted. None is returned if the result is not in the range [min_stamp;max_stamp].

Conversions

val of_span : Span.t -> t option

of_span d is the POSIX time stamp that:

  • Happens at the POSIX span d after epoch if d is positive.
  • Happens at the POSIX span d before epoch if d is negative.

None is returned if the timestamp is not in the range [min_stamp;max_stamp].

val to_span : t -> Span.t

to_span t is the signed POSIX span that happen between t and epoch:

  • If the number is positive t happens after epoch.
  • If the number is negative t happens before epoch.
val of_float_s : float -> t option

of_float_s d is like of_span but with d as a floating point second POSIX span d. This function is compatible with the result of Unix.gettimeofday. Decimal fractional seconds beyond 1e-12 are truncated.

val to_float_s : t -> float

to_float_s t is like to_span but returns a floating point second POSIX span.

Warning. Due to floating point inaccuracies do not expect the function to round trip with of_float_s; especially near Ptime.min_stamp and Ptime.max_stamp.

val pp : Stdlib.Format.formatter -> t -> unit

pp formats an unspecified, approximative, representation of timestamp, it looks like RFC 3339 but it's not do not use for serializing.

The POSIX clock