Documentation in Control.Monad.STM.TMVar - isEmptyTMVar
Hello, As of stm-2.2.0.1, the documentation for the isEmptyTMVar function [1] 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 . [1]: http://hackage.haskell.org/packages/archive/stm/2.2.0.1/doc/html/Control-Con... Best regards, Heinrich Apfelmus -- http://apfelmus.nfshost.com
+1 Excerpts from Heinrich Apfelmus's message of Wed Oct 05 11:38:46 -0400 2011:
Hello,
As of stm-2.2.0.1, the documentation for the isEmptyTMVar function [1] 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 .
[1]: http://hackage.haskell.org/packages/archive/stm/2.2.0.1/doc/html/Control-Con...
Best regards, Heinrich Apfelmus
Heinrich Apfelmus wrote:
As of stm-2.2.0.1, the documentation for the isEmptyTMVar function [1] 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 .
[1]: http://hackage.haskell.org/packages/archive/stm/2.2.0.1/doc/html/Control-Con...
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? Best regards, Heinrich Apfelmus -- http://apfelmus.nfshost.com
On 26/10/2011 19:25, Heinrich Apfelmus wrote:
Heinrich Apfelmus wrote:
As of stm-2.2.0.1, the documentation for the isEmptyTMVar function [1] 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 .
[1]: http://hackage.haskell.org/packages/archive/stm/2.2.0.1/doc/html/Control-Con...
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?
I'll do it. Sorry for the delay, I'm a bit behind with libraries@haskell.org. Cheers, Simon
participants (4)
-
Edward Z. Yang -
Felipe Almeida Lessa -
Heinrich Apfelmus -
Simon Marlow