Skip to content
Newer
Older
100644 198 lines (157 sloc) 7.2 KB
3f42620 @shahn typo cleanup
shahn authored May 23, 2009
1 include::license.txt[]
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
2
3 :language: C
4
5 Connection listeners: accepting TCP connections
6 -----------------------------------------------
7
8 The evconnlistener mechanism gives you a way to listen for and accept
9 incoming TCP connections.
10
11 All the functions and types in this section are declared in
1fa7026 Make version notes more accurate
Nick Mathewson authored Feb 5, 2010
12 event2/listener.h. They first appeared in Libevent 2.0.2-alpha, unless
13 otherwise noted.
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
14
15 Creating or freeing an evconnlistener
16 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
17
18 .Interface
53babe0 Make all examples compile correctly
Nick Mathewson authored Jan 29, 2010
19 [code,C]
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
20 --------
21 struct evconnlistener *evconnlistener_new(struct event_base *base,
22 evconnlistener_cb cb, void *ptr, unsigned flags, int backlog,
23 evutil_socket_t fd);
24 struct evconnlistener *evconnlistener_new_bind(struct event_base *base,
25 evconnlistener_cb cb, void *ptr, unsigned flags, int backlog,
26 const struct sockaddr *sa, int socklen);
27 void evconnlistener_free(struct evconnlistener *lev);
28 --------
29
30 The two evconnlistener_new*() functions both allocate and return a new
31 connection listener object. A connection listener uses an event_base to
32 note when a there is a new TCP connection on a given listener socket.
33 When a new connection arrives, it invokes the callback function you give it.
34
35 In both functions, the 'base' parameter is an event_base that the listener
36 should use to listen for connections. The 'cb' function is a callback to
9d839ae Updates to reference sections for 2.0.9-rc
Nick Mathewson authored Nov 26, 2010
37 invoke when a new connection is received; if 'cb' is NULL, the listener is
38 treated as disabled until a callback is set. The 'ptr' pointer will be passed
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
39 to the callback. The 'flags' argument controls the behavior of the listener
40 -- more on this below. The 'backlog' parameter controls the maximum number
41 of pending connections that the network stack should allow to wait in a
42 not-yet-accepted state at any time; see documentation for your system's
43 listen() function for more details. If 'backlog' is negative, Libevent tries
44 to pick a good value for the backlog; if it is zero, Libevent assumes that
45 you have already called listen() on the socket you are providing it.
46
47 The functions differ in how they set up their listener socket. The
48 evconnlistener_new() function assumes that you have already bound a socket to
49 the port you want to listen on, and that you're passing the socket in as
50 'fd'. If you want Libevent to allocate and bind to a socket on its own,
51 call evconnlistener_new_bind(), and pass in the sockaddr you want to bind to,
52 and its length.
53
8a96d7f Clarify that inputs must be nonblocking, and LEV_OPT_LEAVE_SOCKETS_BL…
Frank Schoep authored Jan 31, 2012
54 TIP: [When using evconnlistener_new, make sure your listening socket is in
55 non-blocking mode by using evutil_make_socket_nonblocking or by manually
56 setting the correct socket option. When the listening socket is left in
57 blocking mode, undefined behavior might occur.]
58
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
59 To free a connection listener, pass it to evconnlistener_free().
60
61 Recognized flags
62 ^^^^^^^^^^^^^^^^
63
64 These are the flags you can pass to the 'flags' argument of the
65 evconnlistener_new() function. You can give any number of these, OR'd
66 together.
67
68 LEV_OPT_LEAVE_SOCKETS_BLOCKING::
8a96d7f Clarify that inputs must be nonblocking, and LEV_OPT_LEAVE_SOCKETS_BL…
Frank Schoep authored Jan 31, 2012
69 By default, when the connection listener accepts a new incoming
70 socket, it sets it up to be nonblocking so that you can use it
71 with the rest of Libevent. Set this flag if you do not want this
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
72 behavior.
73
74 LEV_OPT_CLOSE_ON_FREE::
75 If this option is set, the connection listener closes its
76 underlying socket when you free it.
77
78 LEV_OPT_CLOSE_ON_EXEC::
79 If this option is set, the connection listener sets the
80 close-on-exec flag on the underlying listener socket. See your
81 platform documentation for fcntl and FD_CLOEXEC for more
dacf41f Fix some typos
Robert Ransom authored Feb 20, 2011
82 information.
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
83
84 LEV_OPT_REUSEABLE::
85 By default on some platforms, once a listener socket is closed,
86 no other socket can bind to the same port until a while has
87 passed. Setting this option makes Libevent mark the socket as
88 reusable, so that once it is closed, another socket can be
89 opened to listen on the same port.
90
233b411 Note API changes and clarifications from 2.0.8-rc
Nick Mathewson authored Oct 14, 2010
91 LEV_OPT_THREADSAFE::
92 Allocate locks for the listener, so that it's safe to use it from
93 multiple threads. New in Libevent 2.0.8-rc.
94
7ce95de Add documentation for some functions in 2.1.1-alpha
Nick Mathewson authored Apr 18, 2012
95 LEV_OPT_DISABLED::
96 Initialize the listener to be disabled, not enabled. You can
ca46b10 @mistotebe Fix a few typos
mistotebe authored Jul 4, 2012
97 turn it on manually with evconnlistener_enable(). New in Libevent
7ce95de Add documentation for some functions in 2.1.1-alpha
Nick Mathewson authored Apr 18, 2012
98 2.1.1-alpha.
99
100 LEV_OPT_DEFERRED_ACCEPT::
101 If possible, tell the kernel to not announce sockets as having been
102 accepted until some data has been received on them, and they are ready
154d888 Be more clear that LEV_OPT_DEFERRED_ACCEPT has tricky prereqs
Nick Mathewson authored May 14, 2012
103 for reading. Do not use this option if your protocol
104 _doesn't_ start out with the client transmitting data, since in that case
105 this option will sometimes cause the kernel to never tell you about the
106 connection. Not all operating systems support this option: on ones that
7ce95de Add documentation for some functions in 2.1.1-alpha
Nick Mathewson authored Apr 18, 2012
107 don't, this option has no effect. New in Libevent 2.1.1-alpha.
108
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
109 The connection listener callback
110 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
111
112 .Interface
53babe0 Make all examples compile correctly
Nick Mathewson authored Jan 29, 2010
113 [code,C]
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
114 --------
115 typedef void (*evconnlistener_cb)(struct evconnlistener *listener,
116 evutil_socket_t sock, struct sockaddr *addr, int len, void *ptr);
117 --------
118
119 When a new connection is received, the provided callback function is
120 invoked. The 'listener' argument is the connection listener that
121 received the connection. The 'sock' argument is the new socket
122 itself. The 'addr' and 'len' arguments are the address from which
123 the connection was received and the length of that address
124 respectively. The 'ptr' argument is the user-supplied pointer that
125 was passed to evconnlistener_new().
126
127 Enabling and disabling an evconnlistener
128 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
129
130 .Interface
53babe0 Make all examples compile correctly
Nick Mathewson authored Jan 29, 2010
131 [code,C]
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
132 --------
133 int evconnlistener_disable(struct evconnlistener *lev);
134 int evconnlistener_enable(struct evconnlistener *lev);
135 --------
136
137 These functions temporarily disable or reenable listening for new connections.
138
9d839ae Updates to reference sections for 2.0.9-rc
Nick Mathewson authored Nov 26, 2010
139 Adjusting an evconnlistener's callback
140 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
141
142 .Interface
143 [code,C]
144 --------
145 void evconnlistener_set_cb(struct evconnlistener *lev,
146 evconnlistener_cb cb, void *arg);
147 --------
148
149 This function adjusts the callback and callback argument of an existing
150 evconnlistener. It was introduced in 2.0.9-rc.
151
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
152 Inspecting an evconnlistener
153 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
154
155 .Interface
53babe0 Make all examples compile correctly
Nick Mathewson authored Jan 29, 2010
156 [code,C]
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
157 --------
a77e493 Add and/or fix up some minor interfaces
Nick Mathewson authored Aug 2, 2009
158 evutil_socket_t evconnlistener_get_fd(struct evconnlistener *lev);
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
159 struct event_base *evconnlistener_get_base(struct evconnlistener *lev);
160 --------
161
a77e493 Add and/or fix up some minor interfaces
Nick Mathewson authored Aug 3, 2009
162 These functions return a listener's associated socket and event_base
163 respectively.
164
1fa7026 Make version notes more accurate
Nick Mathewson authored Feb 5, 2010
165 The evconnlistener_get_fd() function first appeared in Libevent 2.0.3-alpha.
166
233b411 Note API changes and clarifications from 2.0.8-rc
Nick Mathewson authored Oct 14, 2010
167 Detecting errors
168 ~~~~~~~~~~~~~~~~
169
170 You can set an error callback that gets informed whenever an accept() call
171 fails on the listener. This can be important to do if you're facing an error
172 condition that would lock the process unless you addressed it.
173
174 .Interface
175 [code,C]
176 --------
177 typedef void (*evconnlistener_errorcb)(struct evconnlistener *lis, void *ptr);
178 void evconnlistener_set_error_cb(struct evconnlistener *lev,
179 evconnlistener_errorcb errorcb);
180 --------
181
182 If you use evconnlistener_set_error_cb() to set an error callback on a
183 listener, the callback will be invoked every time that an error occurs on the
184 listener. It will receive the listener as its first argument, and the
185 argument passed as 'ptr' to evconnlistener_new() as its second argument.
186
187 This function was introduced in Libevent 2.0.8-rc.
188
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
189 Example code: an echo server.
190 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
191
53babe0 Make all examples compile correctly
Nick Mathewson authored Jan 29, 2010
192 //BUILD: SKIP
193 .Example
194 [code,C]
0b322ec New documentation for evconnlistener.
Nick Mathewson authored May 21, 2009
195 --------
196 include::examples_R8/R8_echo_server.c[]
197 --------
Something went wrong with that request. Please try again.