-- 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. -- -- NOTE 2: The vector dependency comes from me not spending time -- figuring out how to pass lists of data to C without first turning them -- into vectors. It'll probably disappear soon. -- -- CAVEAT: I'm not an experienced Haskeller (as you can tell from -- note 2), and this is my first foray into FFI in general. Use with -- caution. @package select @version 0.2 -- | 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) module Control.Concurrent.STM.RunOrElse -- | runOrElse action stm runs the IO action -- action and attempts the STM operation stm, returning -- the return value which is available first. If action returns -- first, then stm is not run. If stm returns first, -- action may or may not complete, but its return value is -- discarded. -- -- runOrTakeTMVar is a special case of this function, where -- stm is simply takeTMVar applied to the given -- TMVar. runOrElse :: IO a -> STM b -> IO (Either a b) -- | 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. -- -- runOrTakeTMVar action tm = runOrElse action -- (takeTMVar tm). -- -- The function was originally made to support selectOrTakeTMVar, -- the reason this library exists. 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. -- -- See also selectOrReadTChan and selectOrElse. Note that -- selectOrTakeTMVar and the former are special cases of the -- latter. -- -- (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) -- | Analogous to selectOrTakeTMVar, except with a general STM -- action in place of taking a TMVar. selectOrElse :: [Fd] -> [Fd] -> [Fd] -> Timeout -> STM a -> IO (Either CInt a) -- | Special case of selectOrElse where the STM action is reading a -- TChan. selectOrReadTChan :: [Fd] -> [Fd] -> [Fd] -> Timeout -> TChan 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