Document deviations from standard functionality

dejafu/Control/Concurrent/Classy.hs

@@ -1,4 +1,16 @@
 -- | Classy concurrency.
+--
+-- Concurrency is \"lightweight\", which means that both thread
+-- creation and context switching overheads are extremely
+-- low. Scheduling of Haskell threads is done internally in the
+-- Haskell runtime system, and doesn't make use of any operating
+-- system-supplied thread packages.
+--
+-- Haskell threads can communicate via @MVar@s, a kind of synchronised
+-- mutable variable (see "Control.Concurrent.Classy.MVar"). Several
+-- common concurrency abstractions can be built from @MVar@s, and
+-- these are provided by the "Control.Concurrent.Classy"
+-- library. Threads may also communicate via exceptions.
 module Control.Concurrent.Classy
   ( module Control.Monad.Conc.Class
   , module Control.Concurrent.Classy.Chan

dejafu/Control/Concurrent/Classy/CRef.hs

@@ -1,4 +1,8 @@
 -- | Mutable references in a concurrency monad.
+--
+-- __Deviations:__ There is no @Eq@ instance for @MonadConc@ the
+-- @CRef@ type. Furthermore, the @mkWeakIORef@ function is not
+-- provided.
 module Control.Concurrent.Classy.CRef
   ( -- * CRefs
     newCRef

dejafu/Control/Concurrent/Classy/Chan.hs

@@ -1,7 +1,10 @@
 -- | Unbounded channels.
 --
--- The @getChanContents@ function from Control.Concurrent.Chan is not
--- provided as it relies on @unsafeInterleaveIO@.
+-- __Deviations:__ @Chan@ as defined here does not have an @Eq@
+-- instance, this is because the @MonadConc@ @MVar@ type does not have
+-- an @Eq@ constraint. The deprecated @unGetChan@ and @isEmptyCHan@
+-- functions are not provided. Furthermore, the @getChanContents@
+-- function is not provided as it needs unsafe I/O.
 module Control.Concurrent.Classy.Chan
   ( -- * The 'Chan' type
     Chan

dejafu/Control/Concurrent/Classy/MVar.hs

@@ -11,6 +11,13 @@
 --
 --   3. As a binary semaphore @'MVar' ()@, with 'takeMVar' and
 --      'putMVar' as wait and signal.
+--
+-- __Deviations:__ There is no @Eq@ instance for @MonadConc@ the
+-- @MVar@ type. Furthermore, the @mkWeakMVar@ and @addMVarFinalizer@
+-- functions are not provided. Finally, normal @MVar@s have a fairness
+-- guarantee, which dejafu does not currently make use of when
+-- generating schedules to test, so your program may be tested with
+-- /unfair/ schedules.
 module Control.Concurrent.Classy.MVar
  ( -- *@MVar@s
   MVar

dejafu/Control/Concurrent/Classy/STM/TArray.hs

@@ -1,6 +1,10 @@
 {-# LANGUAGE FlexibleInstances, MultiParamTypeClasses #-}
 
 -- | TArrays: transactional arrays, for use in STM-like monads.
+--
+-- __Deviations:__ @TArray@ as defined here does not have an @Eq@
+-- instance, this is because the @MonadSTM@ @TVar@ type does not have
+-- an @Eq@ constraint.
 module Control.Concurrent.Classy.STM.TArray (TArray) where
 
 import Data.Array (Array, bounds)

dejafu/Control/Concurrent/Classy/STM/TBQueue.hs

@@ -6,6 +6,11 @@
 -- The implementation is based on the traditional purely-functional
 -- queue representation that uses two lists to obtain amortised /O(1)/
 -- enqueue and dequeue operations.
+--
+-- __Deviations:__ @TBQueue@ as defined here does not have an @Eq@
+-- instance, this is because the @MonadSTM@ @TVar@ type does not have
+-- an @Eq@ constraint. Furthermore, the @newTBQueueIO@ function is not
+-- provided.
 module Control.Concurrent.Classy.STM.TBQueue
   ( -- * TBQueue
     TBQueue

dejafu/Control/Concurrent/Classy/STM/TChan.hs

@@ -1,4 +1,9 @@
 -- | Transactional channels
+--
+-- __Deviations:__ @TChan@ as defined here does not have an @Eq@
+-- instance, this is because the @MonadSTM@ @TVar@ type does not have
+-- an @Eq@ constraint. Furthermore, the @newTChanIO@ and
+-- @newBroadcastTChanIO@ functions are not provided.
 module Control.Concurrent.Classy.STM.TChan
   ( -- * TChans
     TChan

dejafu/Control/Concurrent/Classy/STM/TMVar.hs

@@ -1,4 +1,9 @@
 -- | Transactional @MVar@s, for use with 'MonadSTM'.
+--
+-- __Deviations:__ @TMVar@ as defined here does not have an @Eq@
+-- instance, this is because the @MonadSTM@ @TVar@ type does not have
+-- an @Eq@ constraint. Furthermore, the @newTMVarIO@,
+-- @newEmptyTMVarIO@, and @mkWeakTMVar@ functions are not provided.
 module Control.Concurrent.Classy.STM.TMVar
   ( -- * @TMVar@s
     TMVar

dejafu/Control/Concurrent/Classy/STM/TQueue.hs

@@ -10,6 +10,11 @@
 -- The implementation is based on the traditional purely-functional
 -- queue representation that uses two lists to obtain amortised /O(1)/
 -- enqueue and dequeue operations.
+--
+-- __Deviations:__ @TQueue@ as defined here does not have an @Eq@
+-- instance, this is because the @MonadSTM@ @TVar@ type does not have
+-- an @Eq@ constraint. Furthermore, the @newTQueueIO@ function is not
+-- provided.
 module Control.Concurrent.Classy.STM.TQueue
   ( -- * TQueue
     TQueue

dejafu/Control/Concurrent/Classy/STM/TVar.hs

@@ -1,4 +1,8 @@
 -- | Transactional variables, for use with 'MonadSTM'.
+--
+-- __Deviations:__ There is no @Eq@ instance for @MonadSTM@ the @TVar@
+-- type. Furthermore, the @newTVarIO@ and @mkWeakTVar@ functions are
+-- not provided.
 module Control.Concurrent.Classy.STM.TVar
   ( -- * @TVar@s
     TVar

dejafu/Control/Monad/Conc/Class.hs

@@ -6,6 +6,17 @@
 
 -- | This module captures in a typeclass the interface of concurrency
 -- monads.
+--
+-- __Deviations:__ An instance of @MonadCoonc@ is not required to be
+-- an instance of @MonadFix@, unlike @IO@. The @CRef@, @MVar@, and
+-- @Ticket@ types are not required to be instances of @Show@ or @Eq@,
+-- unlike their normal counterparts. The @threadCapability@,
+-- @threadWaitRead@, @threadWaitWrite@, @threadWaitReadSTM@,
+-- @threadWaitWriteSTM@, and @mkWeakThreadId@ functions are not
+-- provided. The @threadDelay@ function is not required to delay the
+-- thread, merely to yield it. Bound threads are not supported. The
+-- @BlockedIndefinitelyOnMVar@ (and similar) exceptions are /not/
+-- thrown during testing, so do not rely on them at all.
 module Control.Monad.Conc.Class
   ( MonadConc(..)
 

dejafu/Control/Monad/STM/Class.hs

@@ -5,6 +5,15 @@
 
 -- | This module provides an abstraction over 'STM', which can be used
 -- with 'MonadConc'.
+--
+-- This module only defines the 'STM' class; you probably want to
+-- import "Control.Concurrent.Classy.STM" (which exports
+-- "Control.Monad.STM.Class").
+--
+-- __Deviations:__ An instance of @MonadSTM@ is not required to be an
+-- @Alternative@, @MonadPlus@, and @MonadFix@, unlike @STM@. The
+-- @always@ and @alwaysSucceeds@ functions are not provided; if you
+-- need these file an issue and I'll look into it.
 module Control.Monad.STM.Class
   ( MonadSTM(..)
   , check