From 8fee6bfda2138961f529e8814dc6695154b0e8ec Mon Sep 17 00:00:00 2001
From: Laurent Rene de Cotret <l.rdc@socivolta.com>
Date: Wed, 4 Sep 2024 08:02:21 -0400
Subject: [PATCH] Document units of measure for timeout (fixes #340)

---
 packages/distributed-process/ChangeLog                    | 4 ++++
 .../src/Control/Distributed/Process/Internal/CQueue.hs    | 2 +-
 .../Control/Distributed/Process/Internal/Primitives.hs    | 8 ++++++--
 3 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/packages/distributed-process/ChangeLog b/packages/distributed-process/ChangeLog
index a4be0f71..ecbaef7a 100644
--- a/packages/distributed-process/ChangeLog
+++ b/packages/distributed-process/ChangeLog
@@ -1,3 +1,7 @@
+Unreleased
+
+* Added documentation on the unit of measurement for timeout durations (#340)
+
 2024-09-03 Laurent P. René de Cotret <laurent.decotret@outlook.com> 0.7.7
 
 * Bumped dependency bounds to support GHC 8.10.7 - GHC 9.10.1
diff --git a/packages/distributed-process/src/Control/Distributed/Process/Internal/CQueue.hs b/packages/distributed-process/src/Control/Distributed/Process/Internal/CQueue.hs
index 376e6b74..010c8b53 100644
--- a/packages/distributed-process/src/Control/Distributed/Process/Internal/CQueue.hs
+++ b/packages/distributed-process/src/Control/Distributed/Process/Internal/CQueue.hs
@@ -72,7 +72,7 @@ enqueueSTM (CQueue _arrived incoming size) !a = do
 data BlockSpec =
     NonBlocking
   | Blocking
-  | Timeout Int
+  | Timeout Int -- ^ Timeout in microseconds
 
 -- Match operations
 --
diff --git a/packages/distributed-process/src/Control/Distributed/Process/Internal/Primitives.hs b/packages/distributed-process/src/Control/Distributed/Process/Internal/Primitives.hs
index 8598a98a..c40ac807 100644
--- a/packages/distributed-process/src/Control/Distributed/Process/Internal/Primitives.hs
+++ b/packages/distributed-process/src/Control/Distributed/Process/Internal/Primitives.hs
@@ -414,7 +414,9 @@ receiveWait ms = do
 -- If the timeout is zero do a non-blocking check for matching messages. A
 -- non-zero timeout is applied only when waiting for incoming messages (that is,
 -- /after/ we have checked the messages that are already in the mailbox).
-receiveTimeout :: Int -> [Match b] -> Process (Maybe b)
+receiveTimeout :: Int -- ^ Timeout in microseconds
+               -> [Match b] 
+               -> Process (Maybe b)
 receiveTimeout t ms = do
   queue <- processQueue <$> ask
   let blockSpec = if t == 0 then NonBlocking else Timeout t
@@ -1020,7 +1022,9 @@ catchesHandler handlers e = foldr tryHandler (throwM e) handlers
 --------------------------------------------------------------------------------
 
 -- | Like 'expect' but with a timeout
-expectTimeout :: forall a. Serializable a => Int -> Process (Maybe a)
+expectTimeout :: forall a. Serializable a 
+              => Int  -- ^ Timeout in microseconds
+              -> Process (Maybe a)
 expectTimeout n = receiveTimeout n [match return]
 
 -- | Asynchronous version of 'spawn'