hlibev-0.2.3: FFI interface to libev

Network.Libev

Contents

Description

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.

Synopsis

Event loops

type EvLoopPtr = Ptr EvLoopSource

Flags for evDefaultLoop

evRecommendedBackends :: IO CEvFlagTypeSource

Returns the default set of CEvFlagType flags

Locking for event loops

type MutexCallback = EvLoopPtr -> IO ()Source

MutexCallback is called by ev_set_loop_release_cb

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

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.

Event flags

type CEventType = CIntSource

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 = CIntSource

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_io

type EvIoPtr = Ptr EvIoSource

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

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 EvIoPtrSource

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

mkIoCallback :: IoCallback -> IO (FunPtr IoCallback)Source

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.

ev_timer

type EvTimerPtr = Ptr EvTimerSource

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

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 EvTimerPtrSource

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

freeEvTimer :: EvTimerPtr -> IO ()Source

free() an EvTimer

mkTimerCallback :: TimerCallback -> IO (FunPtr TimerCallback)Source

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.

type EvAsyncPtr = Ptr EvAsyncSource

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

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

mkEvAsync :: IO EvAsyncPtrSource

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

freeEvAsync :: EvAsyncPtr -> IO ()Source

free() an EvAsync

mkAsyncCallback :: AsyncCallback -> IO (FunPtr AsyncCallback)Source

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.

Time functions

type EvTimestamp = CDoubleSource

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

evNow :: EvLoopPtr -> IO EvTimestampSource

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

evTime :: IO EvTimestampSource

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 CIntSource

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