quasar: Add documentation about mapFinalizeTOnce being reentrant-safe

queezle42 · Apr 4, 2024 · 0ccd36f · 0ccd36f
1 parent a7972d5
commit 0ccd36f
Showing 1 changed file with 4 additions and 0 deletions.
diff --git a/quasar/src/Quasar/Utils/TOnce.hs b/quasar/src/Quasar/Utils/TOnce.hs
@@ -45,6 +45,7 @@ newTOnceIO initial = liftIO do
   registry <- newCallbackRegistryIO
   TOnce <$> newTVarIO (Left (initial, registry))
 
+-- | Finalizes the `TOnce` by replacing the content, if not already finalized.
 finalizeTOnce :: MonadSTMc NoRetry '[TOnceAlreadyFinalized] m => TOnce a b -> b -> m ()
 finalizeTOnce (TOnce var) value = liftSTMc @NoRetry @'[TOnceAlreadyFinalized] do
   readTVar var >>= \case
@@ -56,6 +57,9 @@ finalizeTOnce (TOnce var) value = liftSTMc @NoRetry @'[TOnceAlreadyFinalized] do
 readTOnce :: MonadSTMc NoRetry '[] m => TOnce a b -> m (Either a b)
 readTOnce (TOnce var) = Bifunctor.first fst <$> readTVar var
 
+-- | Finalizes the `TOnce` by running an STM action.
+--
+-- Reentrant-safe.
 mapFinalizeTOnce :: MonadSTMc NoRetry '[] m => TOnce a (Future b) -> (a -> m (Future b)) -> m (Future b)
 mapFinalizeTOnce (TOnce var) fn = do
   readTVar var >>= \case