More documentation for Announcer module.

1 files changed, 24 insertions, 1 deletions

diff --git a/Announcer.hs b/Announcer.hs
index 140ee993..0a731efa 100644
--- a/Announcer.hs
+++ b/Announcer.hs
@@ -50,6 +50,11 @@ packAnnounceKey _ = return . AnnounceKey . Char8.pack
 unpackAnnounceKey :: Announcer -> AnnounceKey -> STM String
 unpackAnnounceKey _ (AnnounceKey bs) = return $ Char8.unpack bs
 
+-- | Actions that can be scheduled to occur at some particular time in the
+-- future.  Since periodic event handlers are responsible for re-scheduling
+-- themselves, they are typically bootstrapped using 'scheduleImmediately' with
+-- 'NewAnnouncement' which triggers the ordinary recurring scheduling of
+-- 'Announce'.
 data ScheduledItem
     = DeleteAnnouncement
     | NewAnnouncement (STM (IO ())) (IO ()) (IO ()) POSIXTime
@@ -75,8 +80,14 @@ itemStatusNum (StopAnnouncer        ) = 5
 itemStatusNum _                       = error "itemStatusNum not in sync with ScheduledItem declaration."
 
 data Announcer = Announcer
-    { scheduled       :: TVar (PSQ' AnnounceKey POSIXTime ScheduledItem)
+    { -- | The queue of scheduled events.  The priority is the time at which an
+      -- event is supposed to occur.
+      scheduled       :: TVar (PSQ' AnnounceKey POSIXTime ScheduledItem)
+      -- | This TVar is False when the Announcer thread has finished.
     , announcerActive :: TVar Bool
+      -- | This delay is used to wait until it's time to act on the earliest
+      -- scheduled item.  It will be interrupted whenever a new item is
+      -- scheduled.
     , interrutible    :: InterruptibleDelay
     }
 
@@ -88,6 +99,10 @@ data AnnounceState = forall nid addr tok ni r. AnnounceState
     , aStoringNodes :: TVar (MM.MinMaxPSQ ni (Down POSIXTime))
     }
 
+-- | Schedules an event to occur long ago at the epoch (which effectively makes
+-- the event happen as soon as possible).  Note that the caller will usually
+-- also want to interrupt the 'interrutible' delay so that it finds this item
+-- immediately.
 scheduleImmediately :: Announcer -> AnnounceKey -> ScheduledItem -> STM ()
 scheduleImmediately announcer k item
     = modifyTVar' (scheduled announcer) (PSQ.insert' k item 0)
@@ -245,6 +260,14 @@ announceThread announcer = do
     -- We're done.  Let 'stopAnnouncer' know that it can stop blocking.
     atomically $ writeTVar (announcerActive announcer) False
 
+-- | Returns 'Nothing' to stop the announcer thread (when the event is
+-- StopAnnouncer).  Otherwise, returns an action that will be performed in the
+-- announcer thread before looping for the next scheduled item.
+--
+-- Note that the returned action is responsible for re-scheduled another event
+-- for periodic tasks.  Otherwise, as is the case for the 'DeleteAnnouncement'
+-- event, the item associated with a particular announce key will be removed
+-- from the queue.
 performScheduledItem :: Announcer -> POSIXTime -> Binding' AnnounceKey POSIXTime ScheduledItem -> STM (Maybe (IO ()))
 performScheduledItem announcer now = \case