Fast portable non-blocking network programming with Libevent i Fast portable non-blocking network programming with Libevent Fast portable non-blocking network programming with Libevent ii REVISION HISTORY NUMBER DATE DESCRIPTION NAME Fast portable non-blocking network programming with Libevent iii Contents 1 About this document 2 2 A note on examples 2 3 A tiny introduction to asynchronous IO2 3.1 What about convenience? (and what about Windows?)............................... 15 3.2 How efficient is all of this, really?.......................................... 18 4 The Libevent Reference Manual: Preliminaries 18 4.1 Libevent from 10,000 feet.............................................. 18 4.2 The Libraries..................................................... 19 4.3 The Headers...................................................... 20 4.4 If you have to work with an old version of Libevent................................. 20 4.4.1 Notes on version status............................................ 20 5 Setting up the Libevent library 21 5.1 Log messages in Libevent............................................... 21 5.2 Handling fatal errors................................................. 22 5.3 Memory management................................................. 23 5.4 Locks and threading.................................................. 24 5.5 Debugging lock usage................................................. 27 5.6 Debugging event usage................................................ 27 5.7 Detecting the version of Libevent........................................... 29 5.8 Freeing global Libevent structures.......................................... 30 6 Creating an event_base 31 6.1 Setting up a default event_base............................................ 31 6.2 Setting up a complicated event_base......................................... 32 6.3 Examining an event_base’s backend method..................................... 34 6.4 Deallocating an event_base.............................................. 35 6.5 Setting priorities on an event_base.......................................... 36 6.6 Reinitializing an event_base after fork()....................................... 36 6.7 Obsolete event_base functions............................................ 37 7 Working with an event loop 37 7.1 Running the loop................................................... 37 7.2 Stopping the loop................................................... 38 7.3 Re-checking for events................................................ 40 7.4 Checking the internal time cache........................................... 40 7.5 Dumping the event_base status............................................ 40 7.6 Running a function over every event in an event_base................................ 41 7.7 Obsolete event loop functions............................................. 41 Fast portable non-blocking network programming with Libevent iv 8 Working with events 41 8.1 Constructing event objects.............................................. 42 8.1.1 The event flags................................................ 43 8.1.2 About Event Persistence........................................... 44 8.1.3 Creating an event as its own callback argument............................... 44 8.1.4 Timeout-only events............................................. 45 8.1.5 Constructing signal events.......................................... 45 Caveats when working with signals..................................... 46 8.1.6 Setting up events without heap-allocation.................................. 46 8.2 Making events pending and non-pending....................................... 48 8.3 Events with priorities................................................. 48 8.4 Inspecting event status................................................ 49 8.5 Finding the currently running event.......................................... 50 8.6 Configuring one-off events.............................................. 51 8.7 Manually activating an event............................................. 51 8.8 Optimizing common timeouts............................................ 52 8.9 Telling a good event apart from cleared memory................................... 53 8.10 Obsolete event manipulation functions........................................ 54 9 Helper functions and types for Libevent 55 9.1 Basic types...................................................... 55 9.1.1 evutil_socket_t................................................ 55 9.1.2 Standard integer types............................................ 56 9.1.3 Miscellaneous compatibility types...................................... 56 9.2 Timer portability functions.............................................. 56 9.3 Socket API compatibility............................................... 57 9.4 Portable string manipulation functions........................................ 58 9.5 Locale-independent string manipulation functions.................................. 59 9.6 IPv6 helper and portability functions......................................... 59 9.7 Structure macro portability functions......................................... 60 9.8 Secure random number generator........................................... 60 10 Bufferevents: concepts and basics 60 10.1 Bufferevents and evbuffers.............................................. 61 10.2 Callbacks and watermarks.............................................. 61 10.3 Deferred callbacks.................................................. 62 10.4 Option flags for bufferevents............................................. 62 10.5 Working with socket-based bufferevents....................................... 63 10.5.1 Creating a socket-based bufferevent..................................... 63 Fast portable non-blocking network programming with Libevent v 10.5.2 Launching connections on socket-based bufferevents............................ 63 10.5.3 Launching connections by hostname..................................... 64 10.6 Generic bufferevent operations............................................ 66 10.6.1 Freeing a bufferevent............................................. 66 10.6.2 Manipulating callbacks, watermarks, and enabled operations........................ 66 10.6.3 Manipulating data in a bufferevent...................................... 69 10.6.4 Read- and write timeouts........................................... 71 10.6.5 Initiating a flush on a bufferevent...................................... 71 10.7 Type-specific bufferevent functions.......................................... 71 10.8 Manually locking and unlocking a bufferevent.................................... 72 10.9 Obsolete bufferevent functionality.......................................... 72 11 Bufferevents: advanced topics 73 11.1 Paired bufferevents.................................................. 73 11.2 Filtering bufferevents................................................. 74 11.3 Limiting maximum single read/write size...................................... 75 11.4 Bufferevents and Rate-limiting............................................ 75 11.4.1 The rate-limiting model........................................... 76 11.4.2 Setting a rate limit on a bufferevent..................................... 76 11.4.3 Setting a rate limit on a group of bufferevents................................ 76 11.4.4 Inspecting current rate-limit values..................................... 77 11.4.5 Manually adjusting rate limits........................................ 77 11.4.6 Setting the smallest share possible in a rate-limited group.......................... 78 11.4.7 Limitations of the rate-limiting implementation............................... 78 11.5 Bufferevents and SSL................................................. 79 11.5.1 Setting up and using an OpenSSL-based bufferevent............................ 79 11.5.2 Some notes on threading and OpenSSL................................... 82 12 Evbuffers: utility functionality for buffered IO 83 12.1 Creating or freeing an evbuffer............................................ 84 12.2 Evbuffers and Thread-safety............................................. 84 12.3 Inspecting an evbuffer................................................. 84 12.4 Adding data to an evbuffer: basics.......................................... 84 12.5 Moving data from one evbuffer to another...................................... 85 12.6 Adding data to the front of an evbuffer........................................ 85 12.7 Rearranging the internal layout of an evbuffer.................................... 86 12.8 Removing data from an evbuffer........................................... 86 12.9 Copying data out from an evbuffer.......................................... 87 12.10Line-oriented input.................................................. 88 Fast portable non-blocking network programming with Libevent vi 12.11Searching within an evbuffer............................................. 89 12.12Inspecting data without copying it.......................................... 90 12.13Adding data to an evbuffer directly.......................................... 92 12.14Network IO with evbuffers.............................................. 94 12.15Evbuffers and callbacks................................................ 94 12.16Avoiding data copies with evbuffer-based IO..................................... 96 12.17Adding a file to an evbuffer.............................................. 97 12.18Fine-grained control with file segments......................................