Copyright	Copyright 2016 Ertugrul Söylemez
License	Apache License 2.0
Maintainer	Ertugrul Söylemez <esz@posteo.de>
Safe Haskell	Safe
Language	Haskell2010

Data.Time.Class.Clock

Contents

Time

Description

This module exports the ClockTime type, which is related to (but not a wrapper for) the TimeSpec type provided by the clock library. It aims to implement a complete timelike interface to the clock library, so when using this module, you should not need to import System.Clock.

A value of type ClockTime clock denotes a certain point in time as measured by the clock reflected by the clock argument. For example ClockTime Realtime is a point in time as measured by the real-time clock. See the documentation of Clock for a list of available clocks. The type argument is currently only relevant when querying the clock using getTime, and unless the clock type can be inferred from context, you will need to write a suitable type signature. Example:

t <- getTime :: IO (ClockTime Realtime)

The following example measures the duration of the action someOperation:

do t1 <- getTime :: IO (ClockTime Monotonic)
   someOperation
   t2 <- getTime
   let elapsed = diffTime t2 t1

The following example delays the current thread until the start of the next second of real time:

do -- Prints the start time and then delays:
   t' <- getTime :: IO (ClockTime Realtime)
   print t'
   delayUntil 1 (begin Second t')

   -- Should print roughly t' rounded up to the next second:
   t <- getTime
   print t

   -- Prints the amount of time passed:
   print (diffTime t t')

As noted above ClockTime is not a wrapper for TimeSpec, but rather wraps Nano. Arithmetic may be slightly slower, because Integer division is needed, but on 64-bit platforms the difference should be negligible, because the size of a 64-bit word is seldomly exceeded.

Synopsis

Time

newtype ClockTime clock Source

A value of type ClockTime clock is a point in time as measured by the clock represented by clock :: Clock. See the documentation of Clock for the meanings of the individual clocks.

The timeOrigin of all clocks is zero, which has different meanings depending on the chosen clock. For example the origin of the Realtime clock is the epoch.

Constructors

ClockTime
Fields fromClockTime :: Nano

Instances

MonadIO m => GetTime m (ClockTime RealtimeCoarse) Source	Linux only, since Linux 2.6.32.
MonadIO m => GetTime m (ClockTime MonotonicCoarse) Source	Linux only, since Linux 2.6.32.
MonadIO m => GetTime m (ClockTime Boottime) Source	Linux only, since Linux 2.6.39.
MonadIO m => GetTime m (ClockTime MonotonicRaw) Source	Linux only, since Linux 2.6.28.
MonadIO m => GetTime m (ClockTime ThreadCPUTime) Source
MonadIO m => GetTime m (ClockTime ProcessCPUTime) Source
MonadIO m => GetTime m (ClockTime Realtime) Source
MonadIO m => GetTime m (ClockTime Monotonic) Source
Eq (ClockTime clock) Source
Ord (ClockTime clock) Source
Read (ClockTime clock) Source
Show (ClockTime clock) Source
Generic (ClockTime clock) Source
SkipUnit (ClockTime clock) Source
Time (ClockTime clock) Source
TimeOrigin (ClockTime clock) Source
TimeSeconds (ClockTime clock) Source
type Rep (ClockTime clock) Source
type Delta (ClockTime clock) = Nano Source

data Clock :: *

Clock types. A clock may be system-wide (that is, visible to all processes) or per-process (measuring time that is meaningful only within a process). All implementations shall support CLOCK_REALTIME. (The only suspend-aware monotonic is CLOCK_BOOTTIME on Linux.)

Constructors

Monotonic	The identifier for the system-wide monotonic clock, which is defined as a clock measuring real time, whose value cannot be set via `clock_settime` and which cannot have negative clock jumps. The maximum possible clock jump shall be implementation defined. For this clock, the value returned by `getTime` represents the amount of time (in seconds and nanoseconds) since an unspecified point in the past (for example, system start-up time, or the Epoch). This point does not change after system start-up time. Note that the absolute value of the monotonic clock is meaningless (because its origin is arbitrary), and thus there is no need to set it. Furthermore, realtime applications can rely on the fact that the value of this clock is never set.
Realtime	The identifier of the system-wide clock measuring real time. For this clock, the value returned by getTime represents the amount of time (in seconds and nanoseconds) since the Epoch.
ProcessCPUTime	The identifier of the CPU-time clock associated with the calling process. For this clock, the value returned by getTime represents the amount of execution time of the current process.
ThreadCPUTime	The identifier of the CPU-time clock associated with the calling OS thread. For this clock, the value returned by getTime represents the amount of execution time of the current OS thread.
MonotonicRaw	(since Linux 2.6.28; Linux-specific) Similar to CLOCK_MONOTONIC, but provides access to a raw hardware-based time that is not subject to NTP adjustments or the incremental adjustments performed by adjtime(3).
Boottime	(since Linux 2.6.39; Linux-specific) Identical to CLOCK_MONOTONIC, except it also includes any time that the system is suspended. This allows applications to get a suspend-aware monotonic clock without having to deal with the complications of CLOCK_REALTIME, which may have discontinuities if the time is changed using settimeofday(2).
MonotonicCoarse	(since Linux 2.6.32; Linux-specific) A faster but less precise version of CLOCK_MONOTONIC. Use when you need very fast, but not fine-grained timestamps.
RealtimeCoarse	(since Linux 2.6.32; Linux-specific) A faster but less precise version of CLOCK_REALTIME. Use when you need very fast, but not fine-grained timestamps.

Instances

Enum Clock
Eq Clock
Read Clock
Show Clock
Generic Clock
type Rep Clock = D1 D1Clock ((:+:) ((:+:) ((:+:) (C1 C1_0Clock U1) (C1 C1_1Clock U1)) ((:+:) (C1 C1_2Clock U1) (C1 C1_3Clock U1))) ((:+:) ((:+:) (C1 C1_4Clock U1) (C1 C1_5Clock U1)) ((:+:) (C1 C1_6Clock U1) (C1 C1_7Clock U1))))

fromTimeSpec :: TimeSpec -> ClockTime clock Source

Convert the given TimeSpec to a ClockTime value.

Note that the two types are not isomorphic. While TimeSpec is limited to roughly 94 bits, ClockTime does not have such a limit. This function is injective, and the following equation holds:

toTimeSpec . fromTimeSpec = id

toTimeSpec :: ClockTime clock -> TimeSpec Source

Convert the given ClockTime value to a TimeSpec.

Note that the two types are not isomorphic. While TimeSpec is limited to roughly 94 bits, ClockTime does not have such a limit. This function is surjective, and the following equation holds:

toTimeSpec . fromTimeSpec = id