system-time-monotonic-0.2: Simple library for using the system's monotonic clock

PortabilityTested on Linux and Windows
Maintainerjoeyadams3.14159@gmail.com
Safe HaskellSafe-Infered

System.Time.Monotonic.Direct

Contents

Description

This module provides more direct access to the system's monotonic clock, but provides less protection against wraparound.

More specifically, in the higher-level System.Time.Monotonic API, Clock updates its internal disposition every time clockGetTime is called. The only way to get a wraparound issue with the higher-level API is to call clockGetTime very seldomly (e.g. less than once every 24.8 days, if GetTickCount is being used).

Synopsis

Documentation

getSystemClock :: IO SomeSystemClockSource

Return a module used for accessing the system's monotonic clock. The reason this is an IO action, rather than simply a SystemClock value, is that the implementation may need to make a system call to determine what monotonic time source to use, and how to use it.

data SomeSystemClock Source

Existentially-quantified wrapper around SystemClock

Constructors

forall time cumtime . SomeSystemClock (SystemClock time cumtime) 

Instances

data SystemClock time cumtime Source

A SystemClock is a driver module used by Clock to access a particular implementation of monotonic time support.

  • time: Type of value returned by the system's time-getting function.
  • cumtime: Type for accumulating differences between consecutive(-ish) calls to systemClockGetTime, in case time wraps around. The reason we don't simply use DiffTime is this: if the implementation has to divide the result by a clock frequency, it could end up with a number that is not an integral number of picoseconds. Truncating to DiffTime would lose precision, and that precision loss could add up, at least in theory.

Constructors

SystemClock 

Fields

systemClockGetTime :: IO time
 
systemClockDiffTime :: time -> time -> cumtime

systemClockDiffTime new old returns the amount of time that has elapsed between two calls to systemClockGetTime. 

systemClockDiffTime new old = new - old

This function should handle wraparound properly. Also, bear in mind that new may be earlier than old. This can happen if multiple threads are accessing a Clock simultaneously.

Lastly, systemClockDiffTime should not truncate precision in conversion to cumtime. Otherwise, repeated calls to clockGetTime could degrade accuracy, due to lost precision adding up.

systemClockZeroCumTime :: cumtime

The number 0.

systemClockAddCumTime :: cumtime -> cumtime -> cumtime

Add two cumtime values. This should not overflow or lose precision.

systemClockCumToDiff :: cumtime -> DiffTime

Convert a cumulative total of systemClockDiffTime results to DiffTime. This may truncate precision if it needs to.

systemClockName :: String

Label identifying this clock, like "clock_gettime(CLOCK_MONOTONIC)" or "GetTickCount". This label is used for the Show instances of SystemClock and SomeSystemClock, and for clockDriverName.

Instances

Show (SystemClock time cumtime) 

Implementation(s)

The set of definitions below is platform-dependent.

systemClock_MONOTONIC :: SystemClock CTimeSpec DiffTimeSource

Uses clock_gettime with CLOCK_MONOTONIC.

Warning: on Linux, this clock stops when the computer is suspended. See http://lwn.net/Articles/434239/.

data CTimeSpec Source

Instances