fend (Fast EveNt Dispatch)

fend is an event framework utilising LuaJIT's ffi.

It currently has poll and epoll based dispatchers.

The processed C headers in include/ are from a linux x64 system; they may not be suitable for you.

Note: Most functions can raise errors.

Installation

Just place the fend directory in your lua module search path

Modules

File

This module wraps raw file descriptors (usually ints) in a structure to attach methods.

my_file = file.wrap ( fd , no_close )
Wraps the fd in a fend 'file' structure.
fd may be a numeric file descritor or a lua file object.
no_close will skip closing the file on object collection
my_file:getfd ( )
returns the raw file descriptor
my_file:set_blocking ( bool )
sets the O_NONBLOCK flag

Socket

A non-blocking luasocket-like interface

sock = socket.new_tcp ( domain )
Creates a new socket with the given domain (where domain is an AF_*; these can conveniently be found in an addrinfo structure: addrinfo.ai_family (see DNS section))
sock:getfile ( ) Returns the file descriptor for the socket
sock:getfd ( )
Shortcut for sock:getfile():getfd()
sock:set_option ( level , option , val , size )
Calls setsockopt with the given parameters
if val is a number or boolean it will be converted to an int
size is optional, if not passed will be sizeof(val)
sock:set_socket_option ( option , val , size )
Looks up the string option and calls sock:set_option
eg, option = "REUSEADDR"
error_string , errno = sock:get_error ( ) Retrives the error on the socket Returns nil if there is no error
sock:bind ( addrinfo )
sock:bind ( sockaddr , sockaddr_len )
Binds the socket to the interface given in addrinfo or sockaddr , sockaddr_len
sock:listen ( backlog )
Sets the socket to listen with the given backlog (defaults to 128)
sock:accept ( with_sockaddr )
Accepts a new client on sock.
Can return nil if no client is available.
The returned socket will have O_NONBLOCK set.
If with_sockaddr is true, the call will return a sockaddr and length as extra return values
sock:shutdown ( )
Aliased as sock:_shutdown to prevent internal conflicts with the SSL object
n_read = sock:recv ( buff , len , flags )
n_read = sock:receive ( buff , len , flags )
buff should be a user allocated buffer of length len.
flags defaults to 0.
Returns the number of bytes read.
n_read = sock:peek ( buff , len , flags )
Same as sock:recv, but the MSG_PEEK flag is set
n_bytes = sock:send ( buff , len , flags )
Sends buff to the connected peer
If buff is not a const char* then it will have tostring called on it.
If len is not given, it is the length of the string.
flags defaults to 0.
Returns the number of bytes written.
sock:getpeername ( )
Returns a sockaddr and it's length representing the connected peer

SSL

Provides a luasec-like interface (even supporting the same context types)

require "fend.ssl_handshake".handshake ( sock , dispatcher , callback )
Will do an ssl handshake on the given socket, and when complete, call your callback.

DNS

Provides dns and host based utilities.

dns.lookup ( hostname , port , hints )
Completes a blocking lookup, returning an addrinfo structure hints can be NULL or an addrinfo structure
dns.lookup_async ( hostname , port , hints , dispatcher , callback )
Does a non-blocking dns lookup, and when ready.
Will call callback cb with an addrinfo structure.
Returns an object with methods:
wait: blocks until the lookup is completed (or until timeout). returns boolean indicating success/failure

Examples

examples/all.lua [dispatcher]
is a demonstration of every module working together
dispatcher can be either poll or epoll
examples/http_client.lua
is a basic http client
the module returns a table with functions:
request ( url , options , dispatcher , callback )

Extra Information

The include directory contains a partial replication of processed files from the /usr/include directory.

chexiongsheng/fend