Documentation in Control.Monad.STM.TMVar - isEmptyTMVar
apfelmus at quantentunnel.de
Wed Oct 26 20:25:50 CEST 2011
Heinrich Apfelmus wrote:
> As of stm-126.96.36.199, the documentation for the isEmptyTMVar function
>  reads
> isEmptyTMVar :: TMVar a -> STM BoolSource
> Check whether a given TMVar is empty.
> Notice that the boolean value returned is just a snapshot of the state
> of the TMVar. By the time you get to react on its result, the TMVar
> may have been filled (or emptied) - so be extremely careful when using
> this operation. Use tryTakeTMVar instead if possible.
> This being software transactional memory, where everything is wrapped
> into a call to the atomically function, I believe that the second
> paragraph is now completely obsolete, to the point of being misleading
> (it sure scared me). I would be relieved if someone could remove it.
> Most likely, it was originally copied directly from the corresponding
> documentation of Control.Concurrent.MVar .
I forgot to set a discussion period for this, but two weeks have passed
and it seems to me that there is unanimous support for this
documentation change (removing the second paragraph).
I would like to move this towards inclusion in the stm library. Should
I make a track ticket? Or maybe a kind GHC guru shows mercy and applies
the change as it is?
More information about the Libraries