silk.time.mark.

Readings of a monotonic clock: the Mark type.

When to use#

Use a Mark to measure how long something takes and to hold a deadline. A mark comes from a clock that never goes back, such as silk.system.monotonic_clock. For a date and time that you show, store, or send, use silk.time.instant.

Details#

A mark is a point on the timeline of one clock. The origin of that timeline is not specified, so a mark has no date. It has a meaning only next to another mark of the same clock: the later one minus the earlier one is the Duration between them, and a mark plus a span is a deadline. Marks are ordered, so &now >= &deadline tests a deadline.

Gotchas#

The compiler cannot stop a program from comparing marks of two different clocks. The result of such a comparison has no meaning.

Examples#

Compute a deadline and the time left#

silk
import silk.time.duration { Duration }
import silk.time.mark { Mark }

pub fn main() -> i32 {
  // A test clock can make marks from plain numbers. A real clock returns them from `now`.
  let start = Mark.make(100, 0)
  let deadline = start + Duration.fromMilliseconds(1500)
  let now = Mark.make(101, 0)
  if &now >= &deadline {
    return 1
  }
  if &(deadline - now) != &Duration.fromMilliseconds(500) {
    return 2
  }
  return 0
}

Import as Mark with import silk.time.mark { Mark }.

Public declarations: 1.

Mark#

silk
pub struct Mark

A reading of a monotonic clock, with nanosecond precision.

Details#

A mark is the time since the origin of its clock, which is not specified and can be before or after the start of the program. ==, !=, <, <=, >, and >= compare marks. mark + span and mark - span return a mark, and later - earlier returns the span between two marks. They trap when the result is outside the range, which is the range of a Duration.

Implementation Copy for Mark#

silk
impl Copy for Mark

Implementation Mark#

silk
impl Mark

Associated function make#

silk
pub fn make(seconds: i64, nanoseconds: i64) -> Mark

Returns the mark seconds seconds plus nanoseconds nanoseconds after the origin of a clock.

When to use#

A clock provider calls it to build the marks that it returns, and a test calls it for fixed marks. Other code gets marks from a clock.

Details#

Whole seconds in nanoseconds move into the seconds, and both parts can be negative. A total outside the i64 seconds range traps.

Associated function origin#

silk
pub fn origin() -> Mark

Returns the mark at the origin of a clock.

Method sinceOrigin#

silk
pub fn sinceOrigin(self: Self) -> Duration

Returns the time from the origin of the clock to this mark.

Method seconds#

silk
pub fn seconds(self: Self) -> i64

Returns the whole seconds from the origin of the clock, rounded toward negative infinity.

Method subsecondNanoseconds#

silk
pub fn subsecondNanoseconds(self: Self) -> u32

Returns the nanosecond part, from 0 to 999,999,999.

Method checkedAdd#

silk
pub fn checkedAdd(self: Self, span: Duration) -> Option<Mark>

Returns the mark span later, or earlier for a negative span, or None when it is outside the range.

Method checkedSubtract#

silk
pub fn checkedSubtract(self: Self, span: Duration) -> Option<Mark>

Returns the mark span earlier, or later for a negative span, or None when it is outside the range.

Method since#

silk
pub fn since(self: Self, earlier: Mark) -> Duration

Returns the span from earlier to this mark. It is negative when earlier is later.

Gotchas#

Both marks must come from the same clock. A span outside the Duration range traps.

Method until#

silk
pub fn until(self: Self, later: Mark) -> Duration

Returns the span from this mark to later. It is negative when later is earlier.

Gotchas#

Both marks must come from the same clock. A span outside the Duration range traps.

Implementation Equal for Mark#

silk
impl Equal for Mark

Operation equals#

silk
equals: Mark.same

Implementation Order for Mark#

silk
impl Order for Mark

Operation compare#

silk
compare: Mark.compare

Implementation Add<Duration, Mark> for Mark#

silk
impl Add<Duration, Mark> for Mark

Operation add#

silk
add: Mark.addOperator

Implementation Subtract<Duration, Mark> for Mark#

silk
impl Subtract<Duration, Mark> for Mark

Operation subtract#

silk
subtract: Mark.subtractOperator

Implementation Subtract<Mark, Duration> for Mark#

silk
impl Subtract<Mark, Duration> for Mark

Operation subtract#

silk
subtract: Mark.differenceOperator

Implementation Debug for Mark#

silk
impl Debug for Mark

Writes the mark as Mark { elapsed: ... } with the ISO 8601 text of the span.

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Category: Time.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.

View the source of this page