An event framework utilising LuaJIT's ffi. Currently based on epoll.
Lua
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
include
LICENSE
README.mdown
aio.lua
buff_tools.lua
common.lua
dns.lua
epoll.lua file: Return a table with 'wrap' method rather than just a function Oct 7, 2012
file.lua
inotify.lua
poll.lua
signalfd.lua
socket.lua
socket_helpers.lua
ssl.lua
ssl_handshake.lua
timerfd.lua

README.mdown

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.