-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Give the select(2) POSIX function a simple STM interface
--
-- While tinkering on a project, I frequently found myself having to make
-- FFI calls to select(2). This package is an attempt reduce the
-- boilerplate I needed to do that. While at it, I took the opportunity
-- to have what select returns put in a TMVar.
--
-- The package has three parts:
--
--
--
-- NOTE: I feel I'm occupying prime namespace realestate with a
-- package name like select. I'll happily let myself be chased away if
-- anybody else wants to use this package name. Let me know.
--
-- CAVEAT: I'm not an experienced Haskeller, and this is my first
-- foray into FFI in general.
@package select
@version 0.1
-- | Some types used by the other modules in this package.
module System.Posix.IO.Select.Types
type Seconds = Int
type Microseconds = Int
-- | A timeout of Never tells select(2) to never
-- time out, while Time s us sets the timeout parameters
-- to s seconds and us microseconds.
data Timeout
Never :: Timeout
Time :: Seconds -> Microseconds -> Timeout
-- | Interface to the select(2) POSIX function.
module System.Posix.IO.Select
-- | select readFds writeFds exceptFds timeout calls the
-- select(2) function with the file descriptors in
-- readFds as the FD set to watch for read readiness, and
-- similarly for writeFds and exceptFds, with
-- timeout specifying the timeout. The return value is that of
-- the call.
select :: [Fd] -> [Fd] -> [Fd] -> Timeout -> IO CInt
-- | A timeout of Never tells select(2) to never
-- time out, while Time s us sets the timeout parameters
-- to s seconds and us microseconds.
data Timeout
Never :: Timeout
Time :: Seconds -> Microseconds -> Timeout
-- | Perform an IO action, and place its result in a TMVar. See also
-- Control.Concurrent.MVarIO for an MVar version.
module Control.Concurrent.STM.TMVarIO
-- | run action returns a TMVar immediately. The
-- result of action will be placed in said TMVar. If the
-- TMVar is full when action completes, the return value
-- is lost (the action does not wait for an empty TMVar).
run :: IO a -> IO (TMVar a)
-- | This version of run takes an additional TMVar, and
-- returns its content or the result of the IO action, depending
-- on which is available first. Note that the action is not
-- interrupted if the TMVar is the winner, so you may want to make
-- sure it doesn't stick around forever.
--
-- The function was made to support selectOrTakeTMVar, the reason
-- this library exists, and may not be useful outside of that context.
runOrTakeTMVar :: IO a -> TMVar b -> IO (Either a b)
-- | Treat the POSIX select(2) function as a TMVar
-- CInt.
module System.Posix.IO.Select.STM
-- | This version of select immediately returns and makes the return
-- value of the select(2) call available as a TMVar
-- CInt. See select for argument information.
select :: [Fd] -> [Fd] -> [Fd] -> Timeout -> IO (TMVar CInt)
-- | The parameters are the same as for select, except for the
-- addition of a TMVar. The function returns as soon as either the
-- select(2) has completed, or the TMVar is full.
--
-- The return value is either the return value of select(2), or
-- the content of the TMVar. If the TMVar becomes available
-- first, then the select(2) call may hang around forever or
-- until it times out (as specified by the Timeout parameter). If
-- the select(2) returns before the TMVar is available,
-- the TMVar is guaranteed to be left in place.
--
-- (Incidentally, selectOrTakeTMVar is the task I really wanted to
-- accomplish, and solving it just turned into this little library).
selectOrTakeTMVar :: [Fd] -> [Fd] -> [Fd] -> Timeout -> TMVar a -> IO (Either CInt a)
-- | A timeout of Never tells select(2) to never
-- time out, while Time s us sets the timeout parameters
-- to s seconds and us microseconds.
data Timeout
Never :: Timeout
Time :: Seconds -> Microseconds -> Timeout
-- | Perform an IO action, and place its result in an MVar. See also
-- Control.Concurrent.STM.TMVarIO for a TMVar version.
module Control.Concurrent.MVarIO
-- | run action returns an MVar immediately. The
-- result of action will be placed in said MVar. If the
-- MVar is full when action completes, the return value
-- is lost (the action does not wait for an empty MVar).
run :: IO a -> IO (MVar a)
-- | Treat the POSIX select(2) function as an MVar
-- CInt.
module System.Posix.IO.Select.MVar
-- | This version of select immediately returns and makes the return
-- value of the select(2) call available as an MVar
-- CInt. See select for argument information.
select :: [Fd] -> [Fd] -> [Fd] -> Timeout -> IO (MVar CInt)
-- | A timeout of Never tells select(2) to never
-- time out, while Time s us sets the timeout parameters
-- to s seconds and us microseconds.
data Timeout
Never :: Timeout
Time :: Seconds -> Microseconds -> Timeout