Network.Libev

Network.Libev is a low-level binding to the libev library (http://libev.schmorp.de/). The libev documentation is available here: http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod.

Event loops

see http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP

type EvLoopPtr = Ptr EvLoop

evDefaultLoop :: CInt -> IO EvLoopPtr

evLoopNew :: CUInt -> IO EvLoopPtr

evLoop :: EvLoopPtr -> CInt -> IO ()

evUnloop :: EvLoopPtr -> CInt -> IO ()

evLoopDestroy :: EvLoopPtr -> IO ()

Flags for evDefaultLoop

evRecommendedBackends :: IO CEvFlagType

Returns the default set of CEvFlagType flags

evflag_auto :: CEvFlagType

evflag_noenv :: CEvFlagType

evbackend_select :: CEvFlagType

evbackend_poll :: CEvFlagType

evbackend_epoll :: CEvFlagType

evbackend_kqueue :: CEvFlagType

evbackend_devpoll :: CEvFlagType

evbackend_port :: CEvFlagType

Locking for event loops

type MutexCallback = EvLoopPtr -> IO ()

MutexCallback is called by ev_set_loop_release_cb

setupLockingForLoop :: EvLoopPtr -> IO (FunPtr MutexCallback, FunPtr MutexCallback, MVar ())

Set up the given loop for mutex locking from haskell-land -- if you want to touch the loop from other Haskell threads, you'll need to do this. The two FunPtr objects returned need to be explicitly freed with freeMutexCallback.

IMPORTANT: if you want multithreaded access to an EvLoopPtr, you'll have to acquire the MVar returned here (using withMVar) whenever you call any of the ev functions. Very bad C-land crash/bang/boom could otherwise result.

ALSO IMPORTANT: any changes you make to an EvLoopPtr from another thread while the event loop thread is blocked inside ev_loop() will NOT take effect until the the event loop thread unblocks. You'll need to set up an ev_async watcher in order to wake up the event loop thread.

freeMutexCallback :: FunPtr MutexCallback -> IO ()

Event flags

type CEventType = CInt

CEventType is a bitfield used to flag whether a file descriptor is readable, writable, or both. Valid values are ev_read and ev_write. TODO: deprecate and replace by a datatype

type CEvFlagType = CInt

CEvFlagType is a bitfield used to pass flags into evDefaultLoop. Values (evflag_auto, evflag_noenv, etc.) are combined with bitwise or. TODO: replace with a newtype with a monoid instance

ev_read :: CEventType

ev_write :: CEventType

ev_io

See libev docs: http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_io_code_is_this_file_descrip

type EvIoPtr = Ptr EvIo

type IoCallback = EvLoopPtr -> EvIoPtr -> CEventType -> IO ()

An IoCallback is called when a file descriptor becomes readable or writable. It takes a pointer to an ev_loop structure, a pointer to an ev_io structure, and an event mask.

mkEvIo :: IO EvIoPtr

Makes a new ev_io struct using malloc. You are responsible for freeing it with freeEvIo.

freeEvIo :: EvIoPtr -> IO ()

free() an EvIoPtr

mkIoCallback :: IoCallback -> IO (FunPtr IoCallback)

Wrap up an IoCallback so it can be delivered into C-land. This resource is not garbage-collected, you are responsible for freeing it with freeIoCallback.

freeIoCallback :: FunPtr IoCallback -> IO ()

evIoInit :: EvIoPtr -> FunPtr IoCallback -> CInt -> CEventType -> IO ()

evIoStart :: EvLoopPtr -> EvIoPtr -> IO ()

evIoStop :: EvLoopPtr -> EvIoPtr -> IO ()

ev_timer

See libev docs: http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_timer_code_relative_and_opti

type EvTimerPtr = Ptr EvTimer

type TimerCallback = EvLoopPtr -> EvTimerPtr -> CEventType -> IO ()

A TimerCallback is called when a timer expires. It takes a pointer to an ev_loop structure, a pointer to an ev_io structure, and an (unused?) event mask.

mkEvTimer :: IO EvTimerPtr

Makes a new ev_timer struct using malloc. You are responsible for freeing it with freeEvTimer.

freeEvTimer :: EvTimerPtr -> IO ()

free() an EvTimer

mkTimerCallback :: TimerCallback -> IO (FunPtr TimerCallback)

Wrap up a TimerCallback so it can be delivered into C-land. This resource is not garbage-collected, you are responsible for freeing it with freeTimerCallback.

freeTimerCallback :: FunPtr TimerCallback -> IO ()

evTimerInit :: EvTimerPtr -> FunPtr TimerCallback -> EvTimestamp -> EvTimestamp -> IO ()

evTimerStart :: EvLoopPtr -> EvTimerPtr -> IO ()

evTimerStop :: EvLoopPtr -> EvTimerPtr -> IO ()

evTimerAgain :: EvLoopPtr -> EvTimerPtr -> IO ()

evTimerRemaining :: EvLoopPtr -> EvTimerPtr -> IO CDouble

See libev docs: http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_async_code_how_to_wake_up_an

type EvAsyncPtr = Ptr EvAsync

type AsyncCallback = EvLoopPtr -> EvAsyncPtr -> CEventType -> IO ()

An AsyncCallback is called when you wakeup an event loop with ev_async_send

mkEvAsync :: IO EvAsyncPtr

Makes a new ev_async struct using malloc. You are responsible for freeing it with freeEvAsync.

freeEvAsync :: EvAsyncPtr -> IO ()

free() an EvAsync

evAsyncInit :: EvAsyncPtr -> FunPtr AsyncCallback -> IO ()

evAsyncSend :: EvLoopPtr -> EvAsyncPtr -> IO ()

evAsyncStart :: EvLoopPtr -> EvAsyncPtr -> IO ()

evAsyncStop :: EvLoopPtr -> EvAsyncPtr -> IO ()

mkAsyncCallback :: AsyncCallback -> IO (FunPtr AsyncCallback)

Wrap up an AsyncCallback so it can be delivered into C-land. This resource is not garbage-collected, you are responsible for freeing it with freeAsyncCallback.

freeAsyncCallback :: FunPtr AsyncCallback -> IO ()

Time functions

type EvTimestamp = CDouble

Libev timestamp values are C doubles containing the (floating) number of seconds since Jan 1, 1970.

evNow :: EvLoopPtr -> IO EvTimestamp

Fetch a the cached copy of the current time from a loop.

evTime :: IO EvTimestamp

Fetches the current time from the operating system. Usually evNow is preferred since it avoids a context switch by returning a cached value.

C utility functions

c_accept :: CInt -> IO CInt

Calls accept() and sets the socket non-blocking.

c_close :: CInt -> IO CInt

c_read :: CInt -> CString -> CSize -> IO CSize

c_write :: CInt -> CString -> CSize -> IO CSize

c_setnonblocking :: CInt -> IO ()