====== libevent ======
===== Introduction =====

Prosody's core task is to handle multiple client or server connections, and handle incoming data from those connections. Monitoring lots of connections for incoming data efficiently isn't a trivial task, and although the standard [[http://en.wikipedia.org/wiki/POSIX|POSIX]] API provides [[http://man.cx/select(3posix)|select()]] and [[http://man.cx/poll(3posix)|poll()]] for this task, neither scale well for increasing connection counts.

To solve this problem and help people write efficient scalable servers that could make the most of the system's CPU time, many alternative methods started appearing - for example Linux gained '[[http://www.kernel.org/doc/man-pages/online/pages/man4/epoll.4.html|epoll]]' and BSD gained '[[http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2|kqueue]]'. To avoid having server developers work to add support for each method to their application [[http://www.monkey.org/~provos/libevent/|libevent]] was created - a library to provide a standard interface across all the different connection monitoring mechanisms.

In 0.7 Prosody gained optional support for libevent, but still uses select() by default which is still adequate for most servers and requires no additional libraries.

===== Enabling the libevent backend  =====
==== luaevent ====

First of all you need to install luaevent-prosody, a library allowing access to libevent from Lua applications.

You can find the luaevent-prosody source in [[http://code.matthewwild.co.uk/luaevent-prosody|this repository]] and you can grab a tarball of the latest release, [[http://matthewwild.co.uk/uploads/luaevent-prosody-0.1.1.tar.gz|luaevent-prosody 0.1.1]]. Users on Debian, Ubuntu and derived systems can find the //liblua5.1-event-prosody0// package in [[:download:package_repository|our repository]].

For more information on obtaining luaevent-prosody on other platforms, see our [[:doc:depends#luaevent|dependencies page]].

==== Configuration ====

Next you simply need to add the following line to your configuration file, in the global section:

<code lua>
   use_libevent = true
</code>

Restart Prosody and enjoy!