diff options
author | Andreas Klebinger <klebinger.andreas@gmx.at> | 2020-06-22 16:42:57 +0200 |
---|---|---|
committer | Ben Gamari <ben@smart-cactus.org> | 2020-07-15 16:41:03 -0400 |
commit | 12846b85a94b2b73f456e4c441c7890d685deb67 (patch) | |
tree | bf63a07300ad75c7418519a46a076116433baaf2 | |
parent | bd6b8ec1e775441fc943702e93d48ce75f155e9e (diff) | |
download | haskell-12846b85a94b2b73f456e4c441c7890d685deb67.tar.gz |
winio: Update IOPort haddocks.
-rw-r--r-- | libraries/base/GHC/IOPort.hs | 24 |
1 files changed, 16 insertions, 8 deletions
diff --git a/libraries/base/GHC/IOPort.hs b/libraries/base/GHC/IOPort.hs index cb906ae2b0..46a553ca51 100644 --- a/libraries/base/GHC/IOPort.hs +++ b/libraries/base/GHC/IOPort.hs @@ -21,6 +21,9 @@ -- It gives us the ability to have one thread to block, wait for a result from -- another thread and then being woken up. *Nothing* more. -- +-- This type is very much GHC internal. It might be changed or removed without +-- notice in future releases. +-- ----------------------------------------------------------------------------- module GHC.IOPort ( @@ -53,16 +56,23 @@ for communication between concurrent threads, where one of the threads is controlled by an external state. e.g. by an I/O action that is serviced by the runtime. It can be thought of as a box, which may be empty or full. -It is mostly similar to the behavior of MVar except writeIOPort doesn't block if -the variable is full and the GC won't forcibly release the lock if it thinks +It is mostly similar to the behavior of 'Control.Concurrent.MVar.MVar' +except 'writeIOPort' doesn't block if the variable is full and the GC +won't forcibly release the lock if it thinks there's a deadlock. The properties of IOPorts are: * Writing to an empty IOPort will not block. -* Writing to an full IOPort will not block and throw an exception. -* Reading from an IOPort for the second time will throw an exception. +* Writing to an full IOPort will not block. It might throw an exception. +* Reading from an IOPort for the second time might throw an exception. * Reading from a full IOPort will not block, return the value and empty the port. * Reading from an empty IOPort will block until a write. +* Reusing an IOPort (that is, reading or writing twice) is not supported + and might throw an exception. Even if reads and writes are + interleaved. + +This type is very much GHC internal. It might be changed or removed without +notice in future releases. -} @@ -89,18 +99,16 @@ newIOPort value = -- |Atomically read the the contents of the 'IOPort'. If the 'IOPort' is -- currently empty, 'readIOPort' will wait until it is full. After a -- 'readIOPort', the 'IOPort' is left empty. --- TODO: Figure out how to make this an exception for better debugging. -- -- There is one important property of 'readIOPort': -- --- * Only a single threads can be blocked on an 'IOPort', The second thread --- attempting to block will be silently ignored. +-- * Only a single threads can be blocked on an 'IOPort'. -- readIOPort :: IOPort a -> IO a readIOPort (IOPort ioport#) = IO $ \ s# -> readIOPort# ioport# s# -- |Put a value into an 'IOPort'. If the 'IOPort' is currently full, --- 'writeIOPort' will return False and not block. +-- 'writeIOPort' will throw an exception. -- -- There is one important property of 'writeIOPort': -- |