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.