Update docs/refactor for time modules

Author: harendra-kumar

core/src/Streamly/Internal/Data/Time/TimeSpec.hsc

@@ -1,27 +1,33 @@
 {-# OPTIONS_GHC -Wno-identities          #-}
 
-#ifndef __GHCJS__
-#include "config.h"
-#endif
-
-#include "Streamly/Internal/Data/Time/Clock/config-clock.h"
-
-#include "MachDeps.h"
-
 -- |
 -- Module      : Streamly.Internal.Data.Time.TimeSpec
 -- Copyright   : (c) 2019 Composewell Technologies
 -- License     : BSD3
 -- Maintainer  : [email protected]
 -- Stability   : experimental
 -- Portability : GHC
+--
+-- 'TimeSpec' can store upto a duration of ~292 billion years at nanosecond
+-- precision.  An 'Int64' data type is much faster to manipulate but has a
+-- smaller maximum limit (~292 years) at nanosecond precision.  An 'Integer'
+-- type can possibly be used for unbounded fixed precision time. 'Double' can
+-- be used for floating precision time.
 
 module Streamly.Internal.Data.Time.TimeSpec
     (
       TimeSpec(..)
     )
 where
 
+#ifndef __GHCJS__
+#include "config.h"
+#endif
+
+#include "Streamly/Internal/Data/Time/config-clock.h"
+
+#include "MachDeps.h"
+
 import Data.Int (Int64)
 #if (WORD_SIZE_IN_BITS == 32)
 import Data.Int (Int32)
@@ -41,20 +47,27 @@ tenPower9 :: Int64
 tenPower9 = 1000000000
 
 -------------------------------------------------------------------------------
--- TimeSpec representation
+-- TimeSpec
 -------------------------------------------------------------------------------
 
--- A structure storing seconds and nanoseconds as 'Int64' is the simplest and
--- fastest way to store practically large quantities of time with efficient
--- arithmetic operations. If we store nanoseconds using 'Integer' it can store
--- practically unbounded quantities but it may not be as efficient to
--- manipulate in performance critical applications. XXX need to measure the
--- performance.
+-- XXX Should we use "SystemTime" from the "time" package instead?
+--
+-- | 'TimeSpec' can hold up to ~292 billion years at nanosecond precision.
+--
+-- In addition to using the 'TimeSpec' constructor you can also use
+-- 'fromInteger' from the 'Num' type class to create a 'TimeSpec' from
+-- nanoseconds.  Like any 'Num', 'TimeSpec' can be negative.  
+--
+-- Note, we assume that 'nsec' is always less than 10^9. Also, when 'TimeSpec'
+-- is negative then both 'sec' and 'nsec' must be negative.
+-- TODO: Use smart constructors to enforce the assumptions.
+--
+-- Use 'Eq' and 'Ord' instances for comparisons and the 'Num' instance to
+-- perform arithmetic operations on 'TimeSpec'.
 --
--- | Data type to represent practically large quantities of time efficiently.
--- It can represent time up to ~292 billion years at nanosecond resolution.
 data TimeSpec = TimeSpec
   { sec  :: {-# UNPACK #-} !Int64 -- ^ seconds
+  -- XXX this could be Int32 instead
   , nsec :: {-# UNPACK #-} !Int64 -- ^ nanoseconds
   } deriving (Eq, Read, Show)
 
@@ -88,11 +101,12 @@ adjustSign t@(TimeSpec s ns)
 timeSpecToInteger :: TimeSpec -> Integer
 timeSpecToInteger (TimeSpec s ns) = toInteger $ s * tenPower9 + ns
 
+-- | Note that the arithmetic operations may overflow silently.
 instance Num TimeSpec where
     {-# INLINE (+) #-}
     t1 + t2 = adjustSign (addWithOverflow t1 t2)
 
-    -- XXX will this be more optimal if imlemented without "negate"?
+    -- XXX will this be more optimal if implemented without "negate"?
     {-# INLINE (-) #-}
     t1 - t2 = t1 + negate t2
     t1 * t2 = fromInteger $ timeSpecToInteger t1 * timeSpecToInteger t2
@@ -104,7 +118,7 @@ instance Num TimeSpec where
     {-# INLINE signum #-}
     signum (TimeSpec s ns) | s == 0    = TimeSpec (signum ns) 0
                            | otherwise = TimeSpec (signum s) 0
-    -- This is fromNanoSecond64 Integer
+    -- | Convert 'Integer' nanoseconds to 'TimeSpec'.
     {-# INLINE fromInteger #-}
     fromInteger nanosec = TimeSpec (fromInteger s) (fromInteger ns)
         where (s, ns) = nanosec `divMod` toInteger tenPower9

core/src/Streamly/Internal/Data/Time/Units.hs

@@ -1,19 +1,88 @@
 -- |
 -- Module      : Streamly.Internal.Data.Time.Units
 -- Copyright   : (c) 2019 Composewell Technologies
---
--- License     : BSD3
+-- License     : BSD-3-Clause
 -- Maintainer  : [email protected]
 -- Stability   : pre-release
 -- Portability : GHC
 --
+-- Fast time manipulation.
+--
+-- = Representing Time
+--
+-- Numbers along with an associated unit (e.g. 'MilliSecond64') are used to
+-- represent durations and points in time.  Durations are relative but points
+-- are absolute and defined with respect to some fixed or well known point in
+-- time e.g. the Unix epoch (01-Jan-1970).  Absolute and relative times are
+-- numbers that can be represented and manipulated like 'Num'.
+--
+-- = Fixed Precision 64-bit Units
+--
+-- * 'NanoSecond64': 292 years at nanosecond precision.
+-- * 'MicroSecond64': 292K years at nanosecond precision.
+-- * 'MilliSecond64': 292M years at nanosecond precision.
+--
+-- These units are 'Integral' 'Num' types. We can use 'fromIntegral' to convert
+-- any integral type to/from these types.
+--
+-- = TimeSpec
+--
+-- * 'TimeSpec': 292G years at nanosecond precision
+--
+-- = RelTime64
+--
+-- Relative time, not relative to any specific epoch.  Represented using
+-- 'NanoSecond64'. 'fromRelTime64' and 'toRelTime64' can be used to convert a
+-- time unit to/from RelTime. Note that a larger unit e.g. 'MicroSecond64' may
+-- get truncated if it is larger than 292 years. RelTime64 is also generated by
+-- diffing two AbsTime.
+--
+-- RelTime is a 'Num', we can do number arithmetic on RelTime, and use
+-- 'fromInteger' to convert an 'Integer' nanoseconds to 'RelTime'.
+--
+-- = AbsTime
+--
+-- Time measured relative to the POSIX epoch i.e. 01-Jan-1970. Represented
+-- using 'TimeSpec'. 'fromAbsTime' and 'toAbsTime' can be used to convert a
+-- time unit to/from AbsTime.
+--
+-- AbsTime is not a 'Num'. We can use 'diffAbsTime' to diff abstimes to get
+-- a 'RelTime'. We can add RelTime to AbsTime to get another AbsTime.
+--
+-- = TimeSpec vs 64-bit Units
+--
+-- TimeSpec can represent up to 292 billion years of time at nanosecond
+-- precision while 64-bit units can represent only 292 years at the same
+-- precision. However, 64-bit units are much faster to manipulate. In high
+-- performance code it is recommended to use the 64-bit units if possible.
+--
+-- = Working with the "time" package
+--
+-- AbsTime is essentially the same as 'SystemTime' from the time package. We
+-- can use 'SystemTime' to interconvert between time package and this module.
+--
+-- = Alternative Representations
+--
+-- Double or Fixed would be a much better representation so that we do not lose
+-- information between conversions. However, for faster arithmetic operations
+-- we use an 'Int64' here. When we need convservation of values we can use a
+-- different system of units with a Fixed precision.
+--
+-- = TODO
+--
+--  Split the Timespec/TimeUnit in a separate module?
+--  Keep *64/TimeUnit64 in this module, remove the 64 suffix because these are
+--  common units.
+--  Rename TimeUnit to IsTimeSpec, TimeUnit64 to IsTimeUnit.
+--
 -- Time (default double precision). Fast Time (64-bit), Wide Time (TimeSpec).
 -- Timezone, UTC/Local/System/User-defined.
 --
 -- Fast (UTC Time), Wide (Local Time) etc.
 --
 -- Units? Can be module specific or wrappers around them.
 -- e.g. NanoSecond (Fast (UTC Time)) or NanoSecond Time.
+--
 
 module Streamly.Internal.Data.Time.Units
     (
@@ -91,11 +160,6 @@ tenPower9 = 1000000000
 -- NanoSecond Int64
 -- ...
 
--- Double or Fixed would be a much better representation so that we do not lose
--- information between conversions. However, for faster arithmetic operations
--- we use an 'Int64' here. When we need convservation of values we can use a
--- different system of units with a Fixed precision.
-
 -------------------------------------------------------------------------------
 -- Integral Units
 -------------------------------------------------------------------------------
@@ -160,19 +224,21 @@ newtype MilliSecond64 = MilliSecond64 Int64
 -- performance boost. If not then we can just use Integer nanoseconds and get
 -- rid of TimeUnitWide.
 --
+{-
 -- | A type class for converting between time units using 'Integer' as the
 -- intermediate and the widest representation with a nanosecond resolution.
 -- This system of units can represent arbitrarily large times but provides
 -- least efficient arithmetic operations due to 'Integer' arithmetic.
 --
 -- NOTE: Converting to and from units may truncate the value depending on the
 -- original value and the size and resolution of the destination unit.
-{-
 class TimeUnitWide a where
     toTimeInteger   :: a -> Integer
     fromTimeInteger :: Integer -> a
 -}
 
+-- XXX Rename to IsTimeUnit?
+--
 -- | A type class for converting between units of time using 'TimeSpec' as the
 -- intermediate representation.  This system of units can represent up to ~292
 -- billion years at nanosecond resolution with reasonably efficient arithmetic
@@ -262,18 +328,27 @@ instance TimeUnit64 MilliSecond64 where
 -- Absolute time
 -------------------------------------------------------------------------------
 
+-- Have a Fixed64 type with an Int64 as underlying type
+-- XXX Use AbsTime64 for faster arithmetic on AbsTimes?
+--
+-- data Epoch = Posix | UTC | Rel
+--
+-- XXX data Time epoch = Time TimeSpec
+--
 -- | Absolute times are relative to a predefined epoch in time. 'AbsTime'
 -- represents times using 'TimeSpec' which can represent times up to ~292
 -- billion years at a nanosecond resolution.
 newtype AbsTime = AbsTime TimeSpec
     deriving (Eq, Ord, Show)
 
--- | Convert a 'TimeUnit' to an absolute time.
+-- | Convert a 'TimeUnit' representing relative time from the Unix epoch to an
+-- absolute time.
 {-# INLINE_NORMAL toAbsTime #-}
 toAbsTime :: TimeUnit a => a -> AbsTime
 toAbsTime = AbsTime . toTimeSpec
 
--- | Convert absolute time to a 'TimeUnit'.
+-- | Convert absolute time to a relative 'TimeUnit' representing time relative
+-- to the Unix epoch.
 {-# INLINE_NORMAL fromAbsTime #-}
 fromAbsTime :: TimeUnit a => AbsTime -> a
 fromAbsTime (AbsTime t) = fromTimeSpec t
@@ -294,8 +369,10 @@ fromAbsTime (AbsTime t) = fromTimeSpec t
 -- usually shorter and for our purposes an Int64 nanoseconds can hold close to
 -- thousand year duration. It is also faster to manipulate. We do not check for
 -- overflows during manipulations so use it only when you know the time cannot
--- be too big. If you need a bigger RelTime representation then use RelTimeBig.
+-- be too big. If you need a bigger RelTime representation then use RelTime.
 
+-- This is the same as the DiffTime in time package.
+--
 -- | Relative times are relative to some arbitrary point of time. Unlike
 -- 'AbsTime' they are not relative to a predefined epoch.
 newtype RelTime64 = RelTime64 NanoSecond64

src/Streamly/Internal/Data/Stream/IsStream/Transform.hs

@@ -1339,6 +1339,11 @@ indexedR n = fromStreamD . D.indexedR n . toStreamD
 -- Time Indexing
 -------------------------------------------------------------------------------
 
+-- XXX Use the timestamp as (AbsTime, RelTime, a). AbsTime is the time when we
+-- started evaluating the stream and RelTime is the time relative to that.
+-- When we use only RelTime, AbsTime would be discarded by the compiler so it
+-- should not pose any overhead. Have some benchmarks to prove that.
+
 -- Note: The timestamp stream must be the second stream in the zip so that the
 -- timestamp is generated after generating the stream element and not before.
 -- If we do not do that then the following example will generate the same