-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathindex.html
131 lines (129 loc) · 13.8 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libevent: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">libevent
 <span id="projectnumber">2.2.1</span>
</div>
<div id="projectbrief">Event notification library</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">libevent Documentation</div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="intro"></a>
Introduction</h1>
<p>Libevent is an event notification library for developing scalable network servers. The Libevent API provides a mechanism to execute a callback function when a specific event occurs on a file descriptor or after a timeout has been reached. Furthermore, Libevent also support callbacks due to signals or regular timeouts.</p>
<p>Libevent is meant to replace the event loop found in event driven network servers. An application just needs to call <a class="el" href="event_8h.html#a19d60cb72a1af398247f40e92cf07056" title="Event dispatching loop.">event_base_dispatch()</a> and then add or remove events dynamically without having to change the event loop.</p>
<p>Currently, Libevent supports /dev/poll, kqueue(2), select(2), poll(2), epoll(4), and evports. The internal event mechanism is completely independent of the exposed event API, and a simple update of Libevent can provide new functionality without having to redesign the applications. As a result, Libevent allows for portable application development and provides the most scalable event notification mechanism available on an operating system. Libevent can also be used for multithreaded programs. Libevent should compile on Linux, *BSD, Mac OS X, Solaris and, Windows.</p>
<h1><a class="anchor" id="usage"></a>
Standard usage</h1>
<p>Every program that uses Libevent must include the <<a class="el" href="event_8h.html" title="Core functions for waiting for and receiving events, and using event bases.">event2/event.h</a>> header, and pass the -levent flag to the linker. (You can instead link -levent_core if you only want the main event and buffered IO-based code, and don't want to link any protocol code.)</p>
<h1><a class="anchor" id="setup"></a>
Library setup</h1>
<p>Before you call any other Libevent functions, you need to set up the library. If you're going to use Libevent from multiple threads in a multithreaded application, you need to initialize thread support – typically by using <a class="el" href="thread_8h.html#acc0cc708c566c14f4659331ec12f8a5b" title="Sets up Libevent for use with Pthreads locking and thread ID functions.">evthread_use_pthreads()</a> or <a class="el" href="thread_8h.html#a1b0fe36dcb033da2c679d39ce8a190e2" title="Sets up Libevent for use with Windows builtin locking and thread ID functions.">evthread_use_windows_threads()</a>. See <<a class="el" href="thread_8h.html" title="Functions for multi-threaded applications using Libevent.">event2/thread.h</a>> for more information.</p>
<p>This is also the point where you can replace Libevent's memory management functions with event_set_mem_functions, and enable debug mode with <a class="el" href="event_8h.html#a37441a3defac55b5d2513521964b2af5" title="Enable some relatively expensive debugging checks in Libevent that would normally be turned off.">event_enable_debug_mode()</a>.</p>
<h1><a class="anchor" id="base"></a>
Creating an event base</h1>
<p>Next, you need to create an <a class="el" href="structevent__base.html" title="Structure to hold information and state for a Libevent dispatch loop.">event_base</a> structure, using <a class="el" href="event_8h.html#af34c025430d445427a2a5661082405c3" title="Create and return a new event_base to use with the rest of Libevent.">event_base_new()</a> or <a class="el" href="event_8h.html#a864798e5b3c6aa8d2f9e9c5035a3e6da" title="Initialize the event API.">event_base_new_with_config()</a>. The <a class="el" href="structevent__base.html" title="Structure to hold information and state for a Libevent dispatch loop.">event_base</a> is responsible for keeping track of which events are "pending" (that is to say, being watched to see if they become active) and which events are "active". Every event is associated with a single <a class="el" href="structevent__base.html" title="Structure to hold information and state for a Libevent dispatch loop.">event_base</a>.</p>
<h1><a class="anchor" id="event"></a>
Event notification</h1>
<p>For each file descriptor that you wish to monitor, you must create an event structure with <a class="el" href="event_8h.html#a6cd300e5cd15601c5e4570b221b20397" title="Allocate and assign a new event structure, ready to be added.">event_new()</a>. (You may also declare an event structure and call <a class="el" href="event_8h.html#a3e49a8172e00ae82959dfe64684eda11" title="Prepare a new, already-allocated event structure to be added.">event_assign()</a> to initialize the members of the structure.) To enable notification, you add the structure to the list of monitored events by calling <a class="el" href="event_8h.html#ab0c85ebe9cf057be1aa17724c701b0c8" title="Add an event to the set of pending events.">event_add()</a>. The event structure must remain allocated as long as it is active, so it should generally be allocated on the heap.</p>
<h1><a class="anchor" id="loop"></a>
Dispatching events.</h1>
<p>Finally, you call <a class="el" href="event_8h.html#a19d60cb72a1af398247f40e92cf07056" title="Event dispatching loop.">event_base_dispatch()</a> to loop and dispatch events. You can also use <a class="el" href="event_8h.html#acd7da32086d1e37008e7c76c9ea54fc4" title="Wait for events to become active, and run their callbacks.">event_base_loop()</a> for more fine-grained control.</p>
<p>Currently, only one thread can be dispatching a given <a class="el" href="structevent__base.html" title="Structure to hold information and state for a Libevent dispatch loop.">event_base</a> at a time. If you want to run events in multiple threads at once, you can either have a single <a class="el" href="structevent__base.html" title="Structure to hold information and state for a Libevent dispatch loop.">event_base</a> whose events add work to a work queue, or you can create multiple <a class="el" href="structevent__base.html" title="Structure to hold information and state for a Libevent dispatch loop.">event_base</a> objects.</p>
<h1><a class="anchor" id="bufferevent"></a>
I/O Buffers</h1>
<p>Libevent provides a buffered I/O abstraction on top of the regular event callbacks. This abstraction is called a bufferevent. A bufferevent provides input and output buffers that get filled and drained automatically. The user of a buffered event no longer deals directly with the I/O, but instead is reading from input and writing to output buffers.</p>
<p>Once initialized via <a class="el" href="bufferevent_8h.html#a71181be5ab504e26f866dd3d91494854" title="Create a new socket bufferevent over an existing socket.">bufferevent_socket_new()</a>, the bufferevent structure can be used repeatedly with <a class="el" href="bufferevent_8h.html#aa8a5dd2436494afd374213b99102265b" title="Enable a bufferevent.">bufferevent_enable()</a> and <a class="el" href="bufferevent_8h.html#a4f3974def824e73a6861d94cff71e7c6" title="Disable a bufferevent.">bufferevent_disable()</a>. Instead of reading and writing directly to a socket, you would call <a class="el" href="bufferevent_8h.html#a9e36c54f6b0ea02183998d5a604a00ef" title="Read data from a bufferevent buffer.">bufferevent_read()</a> and <a class="el" href="bufferevent_8h.html#a7873bee379202ca1913ea365b92d2ed1" title="Write data to a bufferevent buffer.">bufferevent_write()</a>.</p>
<p>When read enabled the bufferevent will try to read from the file descriptor and call the read callback. The write callback is executed whenever the output buffer is drained below the write low watermark, which is 0 by default.</p>
<p>See <event2/bufferevent*.h> for more information.</p>
<h1><a class="anchor" id="timers"></a>
Timers</h1>
<p>Libevent can also be used to create timers that invoke a callback after a certain amount of time has expired. The evtimer_new() macro returns an event struct to use as a timer. To activate the timer, call evtimer_add(). Timers can be deactivated by calling evtimer_del(). (These macros are thin wrappers around <a class="el" href="event_8h.html#a6cd300e5cd15601c5e4570b221b20397" title="Allocate and assign a new event structure, ready to be added.">event_new()</a>, <a class="el" href="event_8h.html#ab0c85ebe9cf057be1aa17724c701b0c8" title="Add an event to the set of pending events.">event_add()</a>, and <a class="el" href="event_8h.html#a2ffc10a652c67bea16b0a71f7d5a44dc" title="Remove an event from the set of monitored events.">event_del()</a>; you can also use those instead.)</p>
<h1><a class="anchor" id="evdns"></a>
Asynchronous DNS resolution</h1>
<p>Libevent provides an asynchronous DNS resolver that should be used instead of the standard DNS resolver functions. See the <<a class="el" href="dns_8h.html" title="Provides a few APIs to use for resolving DNS names, and a facility for implementing simple DNS server...">event2/dns.h</a>> functions for more detail.</p>
<h1><a class="anchor" id="evhttp"></a>
Event-driven HTTP servers</h1>
<p>Libevent provides a very simple event-driven HTTP server that can be embedded in your program and used to service HTTP requests.</p>
<p>To use this capability, you need to include the <<a class="el" href="http_8h.html" title="Basic support for HTTP serving.">event2/http.h</a>> header in your program. See that header for more information.</p>
<h1><a class="anchor" id="evrpc"></a>
A framework for RPC servers and clients</h1>
<p>Libevent provides a framework for creating RPC servers and clients. It takes care of marshaling and unmarshaling all data structures.</p>
<h1><a class="anchor" id="api"></a>
API Reference</h1>
<p>To browse the complete documentation of the libevent API, click on any of the following links.</p>
<p><a class="el" href="event_8h.html" title="Core functions for waiting for and receiving events, and using event bases.">event2/event.h</a> The primary libevent header</p>
<p><a class="el" href="thread_8h.html" title="Functions for multi-threaded applications using Libevent.">event2/thread.h</a> Functions for use by multithreaded programs</p>
<p><a class="el" href="buffer_8h.html" title="Functions for buffering data for network sending or receiving.">event2/buffer.h</a> and <a class="el" href="bufferevent_8h.html" title="Functions for buffering data for network sending or receiving.">event2/bufferevent.h</a> Buffer management for network reading and writing</p>
<p><a class="el" href="util_8h.html" title="Common convenience functions for cross-platform portability and related socket manipulations.">event2/util.h</a> Utility functions for portable nonblocking network code</p>
<p><a class="el" href="dns_8h.html" title="Provides a few APIs to use for resolving DNS names, and a facility for implementing simple DNS server...">event2/dns.h</a> Asynchronous DNS resolution</p>
<p><a class="el" href="http_8h.html" title="Basic support for HTTP serving.">event2/http.h</a> An embedded libevent-based HTTP server</p>
<p><a class="el" href="rpc_8h.html" title="This header files provides basic support for an RPC server and client.">event2/rpc.h</a> A framework for creating RPC servers and clients</p>
<p><a class="el" href="watch_8h.html" title=""Prepare" and "check" watchers.">event2/watch.h</a> "Prepare" and "check" watchers. </p>
</div></div><!-- PageDoc -->
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.17
</small></address>
</body>
</html>