This repository has been archived by the owner. It is now read-only.
What is Ratchet? ================ The purpose of the ratchet library is to provide a generic socket control mechanism for large numbers of sockets without using threads or losing the ease of synchronous socket programming. Implementations of standard Berkeley sockets are provided, as well as rudimentary support for ZeroMQ sockets, provided versions greater than or equal to 2.1.0 are installed. The polling mechanism is written on top of libevent (http://monkey.org/~provos/libevent/). The ratchet library provides and manages a blend of libevent event loops and Lua coroutines to provide the effect of synchronous socket programming. Each call to a blocking socket (or DNS or ZeroMQ) method actually yields execution until the action is ready to be taken. Ratchet coroutines may also wait for each other. Any application protocol (text-based or binary) can be implemented. Currently, example HTTP and SMTP client and server implementations are provided, see docs for details. The project itself is built using autotools for portability, though it depends on several GNU/Linux features. The project provides a suite of post-build tests which double as sample usages, executed with "make check". Build Information ================= Lua 5.2+ is required to build, as this is a Lua library. Other than that, it should work on most modern GNU/Linux systems with kernel 2.6+ and glibc2. If your distribution or custom install added a suffixes to differentiate Lua versions, you can use the configure option: --with-lua-suffix=ARG Gives suffix for Lua binary and library files. Many distributions do not yet include Lua 5.2 in package management. To avoid blowing away an existing Lua 5.1 install, you might want to install Lua 5.2 somewhere unique. Let's say you installed in /opt/lua-5.2: PATH="/opt/lua-5.2/bin:$PATH" \ CFLAGS="$CFLAGS -I/opt/lua-5.2/include" \ LDFLAGS="$LDFLAGS -I/opt/lua-5.2/lib" \ ./configure If the paths to C and Lua module installation directories are not available from pkg-config, they may need to be manually specified with: --with-lua-cpath=CPATH Install Lua C modules to CPATH --with-lua-lpath=LPATH Install Lua modules to LPATH There are two different ways to use this library: from C or from Lua. By default, both options are made available. If you don't need to use the library from the Lua interpreter, you can choose to disable that with the configure option: --disable-module Disable the Lua module. Similarly, if your Lua installation is custom, or the path to install Lua C modules is not available in pkg-config, you can define a custom installation path for the Lua module with a configure option: --enable-module=PATH Install the Lua module ratchet.so to PATH. If you do not need the developement libraries and headers installed, you can choose to disable them with the configure option: --disable-devel Disable developement headers and libraries. By default, ratchet attempts to build with ZeroMQ (2.1.0+ is required). If you do not need access to ZeroMQ sockets or do not meet the version requirement, you can disable that portion of the library with a configure option: --disable-zeromq Disable usage of ZeroMQ libraries. By default, ratchet uses dns.c to provide enhanced DNS querying. If you do not need access to DNS queries whatsoever, you can disable that portion of the build with the configure option below. Note, however, that currently there is no built-in method to build the data required for BSD sockets without this feature. --disable-dns Disable usage of dns.c libraries. To encrypt socket channels, ratchet can tie in to the OpenSSL suite. This is important, for example, to implement HTTPS or the STARTTLS SMTP command. If included in the build, the OpenSSL global state will be initialized every time a program using the ratchet library is started, regardless of if/when encryption is used (see `SSL_library_init()` and `SSL_load_error_strings()`). OpenSSL will not be included in the build if the following configure option is given: --disable-openssl Disable usage of OpenSSL libraries. For Linux users (see version requirements below), there is access to the timerfd (man page `timerfd_create()`) routines for intelligent time keeping and time-based triggers. If the requirements can't be met, this feature can be disabled with a configure option: --disable-timerfd Disabe usage of timerfd calls. If, for any reason, you do not need access to BSD sockets (for example you only need ZeroMQ, timers, or thread management), you can disable inclusion of these features with another configure option: --disable-socket Disable usage of BSD sockets. Example protocol implementations, installed to the Lua module path, can be disabled with the following configure options: --disable-http Do not install HTTP protocol implementation. --disable-smtp Do not install SMTP protocol implementation. To increase the size of the buffer used when the size of a piece of data is unknown, you can also use the following configure variable. Currently, it only controls the size of the buffer used in `recv()` system calls. BUFSIZ The size of the intermediate buffers used when building large Lua strings. All other configure options are standard from GNU autotools. Dependencies ============ * Lua 5.2+ (http://www.lua.org) * libevent 2+ (http://libevent.org/) * Without --disable-zeromq: ZeroMQ 2.1.0+ (http://www.zeromq.org) * Without --disable-timerfd: Linux kernel 2.6.25+, Glibc 2.8+ * Without --disable-openssl: OpenSSL (http://www.openssl.org/)