-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | epoll bindings
--   
--   Bindings to epoll, a Linux specific I/O event notication facility (cf.
--   man epoll(7)).
@package epoll
@version 0.2


-- | Low level interface to Linux' epoll, a high performance polling
--   mechanism which handles high numbers of file descriptors efficiently.
--   See man epoll(7) for details.
module System.Linux.Epoll.Base

-- | EventType corresponds to epoll's event type defines, e.g. EPOLLIN,
--   EPOLLOUT, EPOLLET, etc.
data EventType

-- | Unsigned type used for length specifications.
data Size
toSize :: Int -> Maybe Size

-- | Unsigned type used for timeout specifications.
data Duration
toDuration :: Int -> Maybe Duration

-- | Event descriptor. Will be returned from <a>add</a> and must be passed
--   to <a>delete</a> exactly once.
data Descriptor a

-- | Abstract epoll device. Holds internal data. Returned from
--   <a>create</a> and used in almost every other API function. Must be
--   closed explicitely with <a>close</a>.
data Device

-- | A single event ocurrence.
data Event a

-- | Match operator. Useful to test whether an <a>EventType</a> returned
--   from <a>wait</a> contains one of the defined event types because
--   EventTypes returned by wait might be the bitwise OR of several
--   EventTypes.
(=~) :: EventType -> EventType -> Bool

-- | Creates an epoll device. Must be closed with <a>close</a>. The
--   parameter <a>Size</a> specifies the number of events that can be
--   reported by a single call to <a>wait</a>.
create :: Size -> IO Device

-- | Closes epoll device.
close :: Device -> IO ()

-- | Waits for the specified duration on all event descriptors. Returns the
--   list of events that occured.
wait :: Duration -> Device -> IO [Event a]

-- | Adds a filedescriptor to the epoll watch set using the specified
--   EventTypes. User data might be passed in as well which will be
--   returned on event occurence as part of the <a>Event</a> type. Returns
--   an event descriptor which must be deleted from the watch set with
--   <a>delete</a> and passed to <a>freeDesc</a> exactly once.
add :: Device -> a -> [EventType] -> Fd -> IO (Descriptor a)

-- | Modified the event types of the event descriptor.
modify :: Device -> [EventType] -> Descriptor a -> IO ()

-- | Removes the event descriptor from the epoll watch set. and frees
--   descriptor which must not be used afterwards.
delete :: Device -> Descriptor a -> IO ()

-- | Frees the resources associated with this descriptor. Must be called
--   exactly once.
freeDesc :: Descriptor a -> IO ()
inEvent :: EventType
outEvent :: EventType
peerCloseEvent :: EventType
urgentEvent :: EventType
errorEvent :: EventType
hangupEvent :: EventType
edgeTriggeredEvent :: EventType
oneShotEvent :: EventType

-- | Bitwise OR of the list of <a>EventType</a>s.
combineEvents :: [EventType] -> EventType
instance Eq Device
instance Show Device
instance Eq Duration
instance Ord Duration
instance Show Duration
instance Eq Size
instance Ord Size
instance Show Size
instance Eq Operation
instance Ord Operation
instance Eq EventType
instance Ord EventType
instance Show Operation
instance Show EventType
instance Storable EventStruct


-- | EventLoop's can be used to get notified when certain events occur on a
--   file descriptor. One can add callback functions for any
--   <a>EventType</a> combination.
module System.Linux.Epoll.EventLoop
data Data

-- | Abstract data type holding bookeeping info.
data Callback

-- | Abstract data type.
data EventLoop

-- | Callback function type
type CallbackFn = Device -> Event Data -> IO ()
type EventMap = [(EventType, CallbackFn)]

-- | Create one event loop which handles up to <a>Size</a> events per call
--   to epoll's <a>wait</a>. An event loop runs until <a>stopEventLoop</a>
--   is invoked, calling <a>wait</a> with a max timeout of 500ms before it
--   waits again.
createEventLoop :: Size -> IO EventLoop

-- | Terminates the event loop and cleans resources. Note that one can only
--   remove callbacks from an eventloop while it is running, so make sure
--   you call this function after all <a>removeCallback</a> calls.
stopEventLoop :: EventLoop -> IO ()

-- | Adds a callback for the given file descriptor to this event loop. The
--   event map specifies for each event type which function to call. event
--   types might be combined using <a>combineEvents</a>.
addCallback :: EventLoop -> Fd -> EventMap -> IO Callback

-- | Removes the callback obtained from <a>addCallback</a> from this event
--   loop. Note that you must not call <a>stopEventLoop</a> before invoking
--   this function.
removeCallback :: EventLoop -> Callback -> IO ()

-- | In case you use <a>oneShotEvent</a> you can re-enable a callback after
--   the event occured. Otherwise no further events will be reported. Cf.
--   epoll(7) for details.
reEnableCallback :: Device -> Data -> Descriptor Data -> IO ()

-- | A combination of <a>peerCloseEvent</a>, <a>errorEvent</a>,
--   <a>hangupEvent</a>.
closeEvents :: EventType


-- | Buffer layer above epoll. Implemented using <a>EventLoop</a>s. The
--   general usage is that first an instance of <a>Runtime</a> is obtained,
--   then one creates as many buffers as needed. Once done with a buffer,
--   it has to be closed and finally the runtime should be shutdown, which
--   kills the event loop, e.g.
--   
--   <pre>
--   do r &lt;- createRuntime (fromJust . toSize $ 4096)
--      withIBuffer r stdInput $ \b -&gt;
--          readBuffer b &gt;&gt;= mapM_ print . take 10 . lines
--      shutdownRuntime r
--   </pre>
--   
--   Please note that one has to close all buffers before calling shutdown
--   on the runtime.
module System.Linux.Epoll.Buffer

-- | Abstract data type for buffer runtime support.
data Runtime

-- | Creates a runtime instance where size denotes the epoll device size
--   (cf. <a>create</a>).
createRuntime :: Size -> IO Runtime

-- | Stops event processing and closes this runtime (and the underlying
--   epoll device).
shutdownRuntime :: Runtime -> IO ()

-- | Buffer Element type class. Any instance of this class can be used as a
--   buffer element.
class BufElem a
beZero :: (BufElem a) => a
beConcat :: (BufElem a) => [a] -> a
beLength :: (BufElem a) => a -> Int
beDrop :: (BufElem a) => Int -> a -> a
beWrite :: (BufElem a) => Fd -> a -> IO Int
beRead :: (BufElem a) => Fd -> Int -> IO (a, Int)

-- | Buffer for reading after <a>inEvent</a>.
data IBuffer a

-- | Create buffer for <a>inEvent</a>s.
createIBuffer :: (BufElem a) => Runtime -> Fd -> IO (IBuffer a)

-- | Close an IBuffer. Must not be called after <a>shutdownRuntime</a> has
--   been invoked.
closeIBuffer :: (BufElem a) => Runtime -> IBuffer a -> IO ()

-- | Exception safe wrapper which creates an IBuffer, passes it to the
--   provided function and closes it afterwards.
withIBuffer :: (BufElem a) => Runtime -> Fd -> (IBuffer a -> IO ()) -> IO ()

-- | Buffer for writing after <a>outEvent</a>.
data OBuffer a

-- | Create Buffer for <a>outEvent</a>s.
createOBuffer :: (BufElem a) => Runtime -> Fd -> IO (OBuffer a)

-- | Close an OBuffer. Must not be called after <a>shutdownRuntime</a> has
--   been invoked.
closeOBuffer :: (BufElem a) => Runtime -> OBuffer a -> IO ()

-- | Exception safe wrapper which creates an OBuffer, passes it to the
--   provided function and flushes and closes it afterwards.
withOBuffer :: (BufElem a) => Runtime -> Fd -> (OBuffer a -> IO ()) -> IO ()

-- | Blocking read. Lazily returns all available contents from
--   <a>IBuffer</a>.
readBuffer :: (BufElem a) => IBuffer a -> IO a

-- | Non-Blocking read. Returns one chunk if available.
readAvail :: (BufElem a) => IBuffer a -> IO (Maybe a)

-- | Blocking read. Returns one chunk from <a>IBuffer</a>.
readChunk :: (BufElem a) => IBuffer a -> IO a

-- | Non-Blocking write. Writes value to buffer which will asynchronously
--   be written to file descriptor.
writeBuffer :: (BufElem a) => OBuffer a -> a -> IO ()

-- | Blocks until buffer is emptied.
flushBuffer :: OBuffer a -> IO ()
instance BufElem String


-- | Re-exports all the public interfaces of <tt>Base</tt>, <tt>Buffer</tt>
--   and <a>EventLoop</a>.
module System.Linux.Epoll