A more flexible replacement for libevent's http API.
C Makefile CMake Shell
Latest commit 2267727 Aug 3, 2016 @ellzey committed on GitHub Update README.markdown
Failed to load latest commit information.
build Cleaning up things a bit Mar 20, 2015
cmake Cleanup time! Apr 2, 2015
compat/sys compat queue.h BSD-only move. Dec 15, 2011
examples Added setsockopt for ipv6 to only use ipv6 null check for ssl via aka… Jul 22, 2015
oniguruma Clean up unused variables in onig Aug 20, 2013
tools Cleanup time! Apr 2, 2015
.gitignore Added build/* to gitignore Apr 5, 2016
.travis.yml travis Apr 21, 2016
CMakeLists.txt Add CPack commands to build a debian package. Feb 24, 2016
ChangeLog release v1.2.11 Nov 2, 2015
Doxyfile [docs] added some doxygen groups Mar 3, 2016
LICENSE LICENSE update for ripping liblz json api May 20, 2016
README.markdown Update README.markdown Aug 3, 2016
evhtp-config.h.in Updates for threading functionality. Nov 26, 2015
evhtp-internal.h rm'd ratelimit, added ability to use je/tc malloc Apr 1, 2015
evhtp.c check for sockopt returns Apr 21, 2016
evhtp.h Merge branch 'develop' of github.com:ellzey/libevhtp into develop Mar 3, 2016
evhtp.pc.in Install into <installdir>/include/evhtp/*.h Mar 20, 2015
evhtp_heap.c added initial lightweight heap allocator May 20, 2016
evhtp_heap.h added initial lightweight heap allocator May 20, 2016
evhtp_json.c Added initial evhtp_json API May 20, 2016
evhtp_json.h Added initial evhtp_json API May 20, 2016
evhtp_numtoa.c Optimizations / assertions / more safe_Free conversions Mar 20, 2015
evhtp_numtoa.h Optimizations / assertions / more safe_Free conversions Mar 20, 2015
evthr.c Updates for threading functionality. Nov 26, 2015
evthr.h Updates for threading functionality. Nov 26, 2015
htparse.c more fixes Apr 21, 2016
htparse.h Optimizations / assertions / more safe_Free conversions Mar 20, 2015
zimg_vs_nginx.png Does image linking work here? Mar 6, 2015




Build Status Coverity Scan Build Status

This document describes details on using the evhtp API. This document is probably not very awesome, it's best to look at test.c to see advanced usage.

Required Dependencies

Optional Dependencies


  • cd build
  • cmake ..
  • make
  • make examples


Libevhtp was created as a replacement API for Libevent's current HTTP API. The reality of libevent's http interface is that it was created as a JIT server, meaning the developer never thought of it being used for creating a full-fledged HTTP service. Infact I am under the impression that the libevent http API was designed almost as an example of what you can do with libevent. It's not Apache in a box, but more and more developers are attempting to use it as so.

Libevent's HTTP pitfalls

  • It was not designed to be a fully functional HTTP server.
  • The code is messy, abstractions are almost non-existent, and feature-creep has made long-term maintainability very hard.
  • The parsing code is slow and requires data to be buffered before a full parse can be completed. This results in extranious memory usage and lots of string comparison functions.
  • There is no method for a user to access various parts of the request processing cycle. For example if the "Content-Length" header has a value of 50000, your callback is not executed until all 50000 bytes have been read.
  • Setting callback URI's do exact matches; meaning if you set a callback for "/foo/", requests for "/foo/bar/" are ignored.
  • Creating an HTTPS server is hard, it requires a bunch of work to be done on the underlying bufferevents.
  • As far as I know, streaming data back to a client is hard, if not impossible without messing with underlying bufferevents.
  • It's confusing to work with, this is probably due to the lack of proper documentation.

Libevhtp attempts to address these problems along with a wide variety of cool mechanisms allowing a developer to have complete control over your server operations. This is not to say the API cannot be used in a very simplistic manner - a developer can easily create a backwards compatible version of libevent's HTTP server to libevhtp.

A bit about the architecture of libevhtp


  1. Create a parent evhtp_t structure.
  2. Assign callbacks to the parent for specific URIs or posix-regex based URI's
  3. Optionally assign per-connection hooks (see hooks) to the callbacks.
  4. Optionally assign pre-accept and post-accept callbacks for incoming connections.
  5. Optionally enable built-in threadpool for connection handling (lock-free, and non-blocking).
  6. Optionally morph your server to HTTPS.
  7. Start the evhtp listener.

Request handling.

  1. Optionally deal with pre-accept and post-accept callbacks if they exist, allowing for a connection to be rejected if the function deems it as unacceptable.
  2. Optionally assign per-request hooks (see hooks) for a request (the most optimal place for setting these hooks is on a post-accept callback).
  3. Deal with either per-connection or per-request hook callbacks if they exist.
  4. Once the request has been fully processed, inform evhtp to send a reply.
A very basic example with no optional conditions.
#include <stdio.h>
#include <evhtp.h>

void testcb(evhtp_request_t * req, void * a) {
    evbuffer_add(req->buffer_out, "foobar", 6);
    evhtp_send_reply(req, EVHTP_RES_OK);

int main(int argc, char ** argv) {
    evbase_t * evbase = event_base_new();
    evhtp_t  * htp    = evhtp_new(evbase, NULL);

    evhtp_set_cb(htp, "/test", testcb, NULL);
    evhtp_bind_socket(htp, "", 8080, 1024);
    event_base_loop(evbase, 0);
    return 0;

Is evhtp thread-safe?

For simple usage with evhtp_use_threads(), yes. But for more extreme cases: sorta, you are bound to the thread mechanisms of libevent itself.

But with proper design around libevhtp, thread issues can be out-of-sight, out-of-mind.

What do you mean by this "proper design" statement?

Refer to the code in ./examples/thread_design.c. The comments go into great detail of the hows and whys for proper design using libevhtp's threading model.

This example uses redis, mainly because most people who have asked me "is evhtp thread-safe" were attempting to other things before sending a response to a request. And on more than one occasion, those other things were communicating with redis.

For Windows MinGW

 cmake -G "MSYS Makefiles" -DCMAKE_INCLUDE_PATH=/mingw/include -DCMAKE_LIBRARY_PATH=/mingw/lib -DCMAKE_INSTALL_PREFIX=/mingw  .

Performance stuff

While we never documented any benchmark publically, the popular open source project ZIMG did a bit of that for us.The ZIMG team decided to move away from NGINX to libevhtp for their software, and the results were pretty outstanding. Here is a graph showing their application under very high load


The X-axis is the number of connections, while the Y-axis is requests per second.

You can read the whole article here: Architecture Design of an Image Server

Slightly outdated (Now faster!) HI NGINX

Coverity Scan Build Status