1 |
<?xml version="1.0" encoding="ISO-8859-1"?> |
2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11-strict.dtd"> |
3 |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> |
4 |
<head> |
5 |
<meta http-equiv="Content-Style-Type" content="text/css"/> |
6 |
<style type="text/css">@import "style.css";</style> |
7 |
<title>IRC Services Technical Reference Manual - 3. Communication (socket) handling</title> |
8 |
</head> |
9 |
|
10 |
<body> |
11 |
<h1 class="title" id="top">IRC Services Technical Reference Manual</h1> |
12 |
|
13 |
<h2 class="section-title">3. Communication (socket) handling</h2> |
14 |
|
15 |
<p class="section-toc"> |
16 |
3-1. <a href="#s1">Overview</a> |
17 |
<br/>3-2. <a href="#s2">Creating, configuring, and destroying sockets</a> |
18 |
<br/> 3-2-1. <a href="#s2-1">Interface routines</a> |
19 |
<br/> 3-2-2. <a href="#s2-2">Socket callbacks</a> |
20 |
<br/>3-3. <a href="#s3">Establishing and breaking connections</a> |
21 |
<br/> 3-3-1. <a href="#s3-1">Outgoing connections</a> |
22 |
<br/> 3-3-2. <a href="#s3-2">Incoming connections</a> |
23 |
<br/> 3-3-3. <a href="#s3-2">Disconnecting</a> |
24 |
<br/>3-4. <a href="#s4">Sending and receiving data</a> |
25 |
<br/> 3-4-1. <a href="#s4-1">Sending data</a> |
26 |
<br/> 3-4-2. <a href="#s4-2">Receiving data</a> |
27 |
<br/> 3-4-3. <a href="#s4-3">Muting sockets</a> |
28 |
<br/>3-5. <a href="#s5">Retrieving socket information</a> |
29 |
<br/>3-6. <a href="#s6">The socket polling routine</a> |
30 |
</p> |
31 |
|
32 |
<p class="backlink"><a href="2.html">Previous section: Core Services functionality</a> | |
33 |
<a href="index.html">Table of Contents</a> | |
34 |
<a href="4.html">Next section: The module system</a></p> |
35 |
|
36 |
<!------------------------------------------------------------------------> |
37 |
<hr/> |
38 |
|
39 |
<h3 class="subsection-title" id="s1">3-1. Overview</h3> |
40 |
|
41 |
<p>In Services, all network communication is performed through the socket |
42 |
subsystem, defined in the files <tt>sockets.c</tt> and <tt>sockets.h</tt>. |
43 |
This subsystem provides routines for managing sockets, which have a type of |
44 |
<tt>Socket *</tt>, connecting to or accepting connections from the |
45 |
network, and sending and receiving data.</p> |
46 |
|
47 |
<p>All network communication in Services is performed asynchronously. Send |
48 |
(write) operations buffer the data given and return immediately; receive |
49 |
(read) operations are performed via <i>callbacks</i>, functions called by |
50 |
the central polling routine when particular events occur, and the actual |
51 |
reading routines operate on a read buffer which is filled by the polling |
52 |
routine as data is received from the remote host. The polling routine |
53 |
itself is called by the Services main loop.</p> |
54 |
|
55 |
<p>The socket subsystem is designed so that it can be used in other |
56 |
programs as well with minimal changes. (In fact, I currently use it in the |
57 |
HTTP server I wrote for my personal domain.) Note, however, that only TCP |
58 |
connections over IPv4 are supported. The socket subsystem uses the |
59 |
following functions from other Services source files, so replacements or |
60 |
stubs will need to be provided: <tt>log()</tt>, <tt>log_perror()</tt>, |
61 |
<tt>log_debug()</tt>, <tt>log_perror_debug()</tt>, <tt>pack_ip()</tt>.</p> |
62 |
|
63 |
<p>Below, <a href="#s2">section 3-2</a> discusses the creation and |
64 |
management of socket objects, including a list of callbacks; |
65 |
<a href="#s3">section 3</a> discusses connecting to (and listening for |
66 |
connections from) remote hosts; <a href="#s4">section 3-4</a> discusses |
67 |
sending and receiving data; <a href="#s5">section 3-5</a> discusses |
68 |
functions for retrieving information about sockets; and |
69 |
<a href="#s6">section 3-6</a> discusses the socket polling routine in |
70 |
detail.</p> |
71 |
|
72 |
<p>All socket routines which can fail return a valid error code in the |
73 |
system variable <tt>errno</tt> on failure. The error codes returned are |
74 |
generally the same as those returned by the equivalent system calls or |
75 |
standard library functions; special note of particular error codes is |
76 |
included where appropriate.</p> |
77 |
|
78 |
<p>There are a few preprocessor constants and macros used in the source |
79 |
that are worth mentioning:</p> |
80 |
|
81 |
<dl> |
82 |
<dt><tt><b>SOCK_MIN_BUFSIZE</b></tt></dt> |
83 |
<dd>Sets both the minimum socket buffer size and the increment by which |
84 |
the buffer size is increased when necessary. Defined in |
85 |
<tt>sockets.h</tt>.</dd> |
86 |
|
87 |
<dt><tt><b>WARN_ON_BUFSIZE</b></tt></dt> |
88 |
<dd>If defined, causes a warning message to be logged when a socket's |
89 |
read or write buffer cannot be expanded due to the per-connection |
90 |
or total buffer size limit (as set by <tt>sock_set_buflimits()</tt>). |
91 |
Only one warning is logged per socket. Optionally defined in |
92 |
<tt>sockets.c</tt>.</dd> |
93 |
|
94 |
<dt><tt><b>DISABLE_SWRITEMAP</b></tt></dt> |
95 |
<dd>If defined, disables the <tt>swritemap()</tt> function (see |
96 |
<a href="#s4">section 3-4</a>), removing a dependency on the |
97 |
<tt>munmap()</tt> system call and the <tt>sys/mman.h</tt> header |
98 |
file. Optionally defined in <tt>sockets.c</tt>.</dd> |
99 |
|
100 |
<dt><tt><b>TRACE_CALLS</b></tt></dt> |
101 |
<dd>If defined, enables tracing of function calls (entry and exit) via |
102 |
<tt>log_debug()</tt>. Optionally defined in <tt>sockets.c</tt>.</dd> |
103 |
|
104 |
<dt><tt><b>ENTER</b>(<i>fmt</i>,...)</tt> |
105 |
<br/><tt><b>ENTER_WITH</b>(<i>retfmt</i>, <i>fmt</i>,...)</tt></dt> |
106 |
<dd>Used in function call tracing to log entry to a function, along |
107 |
with the values of any parameters. <tt><i>fmt</i></tt> is a |
108 |
<tt>printf()</tt>-style format string (which must be a string |
109 |
literal) for formatting the function parameter values (passed as |
110 |
extra parameters to the macro), and should cause each parameter to |
111 |
be written in an appropriate format separated by commas. |
112 |
<tt>ENTER_WITH()</tt> is used for functions which return a value, |
113 |
and takes an extra parameter, <tt><i>retfmt</i></tt>, which is the |
114 |
format string to use to display the return value, such as |
115 |
<tt>"%d"</tt> or <tt>"%p"</tt> (the parameter is passed here to |
116 |
avoid having to include it at every return point). These macros |
117 |
do nothing if function call tracing is not enabled. Defined in |
118 |
<tt>sockets.c</tt>.</dd> |
119 |
|
120 |
<dt><tt><b>RETURN</b></tt> |
121 |
<br/><tt><b>RETURN_WITH</b>(<i>val</i>)</tt></dt> |
122 |
<dd>Used in function tracing to log exit from a function (and |
123 |
perform the <tt>return</tt> as well). <tt>RETURN</tt> is used for |
124 |
<tt>void</tt> functions, while <tt>RETURN_WITH()</tt> is used for |
125 |
functions that return a value. If function call tracing is not |
126 |
enabled, these macros simply perform a <tt>return</tt>. Defined in |
127 |
<tt>sockets.c</tt>.</dd> |
128 |
</dl> |
129 |
|
130 |
<p class="backlink"><a href="#top">Back to top</a></p> |
131 |
|
132 |
<!------------------------------------------------------------------------> |
133 |
<hr/> |
134 |
|
135 |
<h3 class="subsection-title" id="s2">3-2. Creating, configuring, and destroying sockets</h3> |
136 |
|
137 |
<p>Before any other operations can be performed, a socket object must be |
138 |
created, either explicitly or by accepting a connection from a listener |
139 |
socket (see <a href="#s3-2">section 3-3-2</a>. Socket objects are the |
140 |
means by which the socket subsystem keeps track of sockets, and are used |
141 |
in place of system socket descriptors with all relevant functions.</p> |
142 |
|
143 |
<p>Before actually establishing a connection, certain aspects of socket |
144 |
behavior can be configured. In particular, it is important to set up |
145 |
proper callback routines (see <a href="#s2-2">section 3-2-2</a>) or you |
146 |
will be unable to do anything useful with the socket! Sockets can also be |
147 |
set to be blocking (applying only to write operations occurring then the |
148 |
write buffer is full), and a write timeout can be set, causing the socket |
149 |
to be automatically disconnected if a certain amount of time passes without |
150 |
being able to send any data to the remote host. All configuration routines |
151 |
can be called regardless of whether the socket is connected or not.</p> |
152 |
|
153 |
<p>When a socket object is no longer needed, it should be destroyed in |
154 |
order to free resources used by the socket. If a connected socket is |
155 |
destroyed, it is automatically disconnected first.</p> |
156 |
|
157 |
<p class="backlink"><a href="#top">Back to top</a></p> |
158 |
|
159 |
|
160 |
<h4 class="subsubsection-title" id="s2-1">3-2-1. Interface routines</h4> |
161 |
|
162 |
<p>The following routines are used for creating, configuring, and |
163 |
destroying sockets:</p> |
164 |
|
165 |
<dl> |
166 |
<dt><tt>Socket *sock_new()</tt></dt> |
167 |
<dd>Creates and returns a new, unconnected socket object. The socket |
168 |
has no callbacks associated with it, and defaults to no write |
169 |
timeout and non-blocking mode. The socket's internal read and |
170 |
write buffers are each created with a size of |
171 |
<tt>SOCK_MIN_BUFSIZE</tt> bytes.</dd> |
172 |
|
173 |
<dt><tt>void sock_setcb(Socket *<i>s</i>, SocketCallbackID <i>which</i>, |
174 |
SocketCallback <i>func</i>)</tt></dt> |
175 |
<dd>Sets the function for the callback event selected by |
176 |
<tt><i>which</i></tt> (one of the <tt>SCB_*</tt> constants) to the |
177 |
function <tt><i>func</i></tt> for the given socket. If |
178 |
<tt><i>func</i></tt> is <tt>NULL</tt>, then no function will be |
179 |
called for the selected callback event.</dd> |
180 |
|
181 |
<dt><tt>sock_set_wto(Socket *<i>s</i>, int <i>seconds</i>)</tt></dt> |
182 |
<dd>Sets the write timeout for the given socket to |
183 |
<tt><i>seconds</i></tt> seconds. If data is buffered for sending |
184 |
and no data can be sent within the specified interval, the socket |
185 |
will automatically be disconnected, as if the remote host had |
186 |
closed the connection. A value of zero for <tt><i>seconds</i></tt> |
187 |
clears the timeout, allowing data to be buffered indefinitely.</dd> |
188 |
|
189 |
<dt><tt>sock_set_blocking(Socket *<i>s</i>, int <i>blocking</i>)</tt></dt> |
190 |
<dd>Sets whether write operations should block or return an error |
191 |
(<tt>EAGAIN</tt>) if no buffer space is available for data passed |
192 |
to one of the send routines and the remote host is not ready to |
193 |
accept more data. Note that if sufficient buffer space is |
194 |
available, write operations will always return immediately |
195 |
regardless of this setting.</dd> |
196 |
|
197 |
<dt><tt>void sock_free(Socket *<i>s</i>)</tt></dt> |
198 |
<dd>Destroys the given socket, freeing all resources used by the |
199 |
socket. If the socket is connected to a remote host, the |
200 |
connection is automatically terminated, as if <tt>disconn()</tt> |
201 |
(see <a href="#s3-3">section 3-3-3</a>) had been called.</dd> |
202 |
</dl> |
203 |
|
204 |
<p>There are two other routines which operate on the socket subsystem as a |
205 |
whole, rather then on a particular socket:</p> |
206 |
|
207 |
<dl> |
208 |
<dt><tt>sock_set_buflimits(uint32 <i>per_conn</i>, uint32 <i>total</i>)</tt></dt> |
209 |
<dd>Sets the maximum combined send and receive buffer size allowed for |
210 |
a single socket (first parameter) and for all sockets as a whole |
211 |
(second parameter), in bytes. Any data that arrives when one of |
212 |
these limits has been reached will not be received until buffer |
213 |
space becomes available; any send operations performed will fail if |
214 |
no space is available. A value of zero for either parameter |
215 |
disables the respective limit; any other value is rounded down to a |
216 |
multiple of <tt>SOCK_MIN_BUFSIZE</tt> (values smaller than |
217 |
<tt>SOCK_MIN_BUFSIZE</tt> are rounded up).</dd> |
218 |
|
219 |
<dt><tt>sock_set_rto(int <i>msec</i>)</tt></dt> |
220 |
<dd>Sets the read timeout used by the socket polling routine, in |
221 |
milliseconds. If no socket activity occurs during this interval, |
222 |
the polling routine will return control to its caller. Zero is a |
223 |
valid value, and tells the polling routine to return immediately if |
224 |
no data has been received by the system. A negative value disables |
225 |
the timeout, causing the polling routine to wait indefinitely for |
226 |
socket activity.</dd> |
227 |
</dl> |
228 |
|
229 |
<p class="backlink"><a href="#top">Back to top</a></p> |
230 |
|
231 |
|
232 |
<h4 class="subsubsection-title" id="s2-2">3-2-2. Socket callbacks</h4> |
233 |
|
234 |
<p>As mentioned above, the socket subsystem makes use of <i>callbacks</i> |
235 |
for socket activity processing. Rather than having the caller code |
236 |
explicitly read from the socket, potentially blocking if no data is |
237 |
available, a polling routine (discussed in <a href="#s6">section 3-6</a>) |
238 |
monitors all sockets for activity, "calling back" to the caller when |
239 |
certain events occur. The functions to be called for each event can be |
240 |
set independently for each socket, using the aforementioned |
241 |
<tt>sock_setcb()</tt> routine; events to which no function is assigned |
242 |
(the default state) are ignored. Two parameters are passed to the callback |
243 |
function: a <tt>Socket *</tt> parameter indicating the socket on which |
244 |
the event occured, and a <tt>void *</tt> parameter whose meaning |
245 |
depends on the particular callback (some callbacks do not use it at all). |
246 |
The exact callback function signature is:</p> |
247 |
|
248 |
<div class="code">void <i>callback</i>(Socket *<i>s</i>, void *<i>param</i>)</div> |
249 |
|
250 |
<p>This type (a pointer to it, rather) is defined as <tt>SocketCallback</tt> |
251 |
in <tt>sockets.h</tt>.</p> |
252 |
|
253 |
<p>The following events (listed by the name of the constant used as the |
254 |
<tt><i>which</i></tt> parameter to <tt>sock_setcb()</tt>) can have callback |
255 |
functions attached to them:</p> |
256 |
|
257 |
<dl> |
258 |
<dt><tt><b>SCB_CONNECT</b></tt></dt> |
259 |
<dd>Called when a connection initiated by calling the <tt>conn()</tt> |
260 |
routine (see <a href="#s3-1">section 3-3-1</a>) completes |
261 |
successfully. The <tt>void *</tt> parameter is not used.</dd> |
262 |
|
263 |
<dt><tt><b>SCB_DISCONNECT</b></tt></dt> |
264 |
<dd>Called when an existing connection is broken, either by the remote |
265 |
host or by calling the <tt>disconn()</tt> routine (see |
266 |
<a href="#s3-3">section 3-3-3</a>), or when a connection initiated |
267 |
by calling the <tt>conn()</tt> routine fails. The |
268 |
<tt>void *</tt> parameter indicates the type of disconnection: |
269 |
<ul><li><b><tt>DISCONN_LOCAL</tt>:</b> The connection was broken |
270 |
locally by calling the <tt>disconn()</tt> routine.</li> |
271 |
<li><b><tt>DISCONN_REMOTE</tt>:</b> The connection was broken |
272 |
by the remote host.</li> |
273 |
<li><b><tt>DISCONN_CONNFAIL</tt>:</b> The connection attempt |
274 |
was rejected by the remote host or otherwise failed.</li></ul> |
275 |
For remote disconnection events (<tt>DISCONN_REMOTE</tt> and |
276 |
<tt>DISCONN_CONNFAIL</tt>), the global <tt>errno</tt> variable |
277 |
indicates the cause of the disconnection if known, zero |
278 |
otherwise.</dd> |
279 |
|
280 |
<dt><tt><b>SCB_ACCEPT</b></tt></dt> |
281 |
<dd>Called when a remote host connects to a listener socket (see |
282 |
<a href="#s3-2">section 3-3-2</a>). The primary socket parameter |
283 |
to the callback is the listener socket, and the |
284 |
<tt>void *</tt> parameter is the newly-created socket (of type |
285 |
<tt>Socket *</tt>). Note that listener sockets will |
286 |
immediately drop all incoming connections if no function is |
287 |
assigned to this callback.</dd> |
288 |
|
289 |
<dt><tt><b>SCB_READ</b></tt></dt> |
290 |
<dd>Called when data has been received on the socket and is available |
291 |
for reading (see <a href="#s4-2">section 3-4-2</a>). The |
292 |
<tt>void *</tt> parameter, cast to <tt>uint32</tt>, is the |
293 |
number of bytes of data available for reading.</dd> |
294 |
|
295 |
<dt><tt><b>SCB_READLINE</b></tt></dt> |
296 |
<dd>Called when data has been received on the socket and is available |
297 |
for reading, much like <tt>SCB_READ</tt>; however, this callback is |
298 |
only called when a full line of data (containing a newline) is |
299 |
available to be read. If both this callback and <tt>SCB_READ</tt> |
300 |
have functions assigned to them, both functions will be called in |
301 |
turn until there is no more data to process; see |
302 |
<a href="#s4-2">section 3-4-2</a> for details.</dd> |
303 |
|
304 |
<dt><tt><b>SCB_TRIGGER</b></tt></dt> |
305 |
<dd>Called when a <i>write trigger</i> is encountered on the socket. |
306 |
Write triggers are created using the <tt>swrite_trigger()</tt> |
307 |
routine, described in <a href="#s4-1">section 3-4-1</a>. A write |
308 |
trigger causes this callback to be called when all data before the |
309 |
trigger has been successfully sent to the remote host, but before |
310 |
any data beyond the trigger has been sent. The |
311 |
<tt>void *</tt> parameter is the arbitrary value passed to |
312 |
<tt>swrite_trigger()</tt>.</dd> |
313 |
</dl> |
314 |
|
315 |
<p>Internally, callback functions are called using the local |
316 |
<tt>do_callback()</tt> routine. This routine sets the <tt>SF_CALLBACK</tt> |
317 |
flag on the socket while the callback is in progress, to ensure that the |
318 |
socket is not destroyed while it is still in use. The routine also checks |
319 |
after the callback returns whether any flags were set indicating that the |
320 |
connection was broken (<tt>SF_BROKEN</tt>) or that the socket should be |
321 |
destroyed (<tt>SF_DELETEME</tt>) or disconnected locally |
322 |
(<tt>SF_DISCONNECT</tt>). The function returns 0 if the socket was |
323 |
disconnected, 1 otherwise. It also returns 1 if either the socket or the |
324 |
callback is unspecified (<tt>NULL</tt> or zero), to simplify the caller's |
325 |
logic.</p> |
326 |
|
327 |
<p class="backlink"><a href="#top">Back to top</a></p> |
328 |
|
329 |
<!------------------------------------------------------------------------> |
330 |
<hr/> |
331 |
|
332 |
<h3 class="subsection-title" id="s3">3-3. Establishing and breaking connections</h3> |
333 |
|
334 |
<p>From the point of view of any particular host, there are two general |
335 |
ways in which a connection to a remote host can be established: either by |
336 |
actively connecting to the remote host (outgoing), or by waiting for the |
337 |
remote host to request a connection (incoming). The socket subsystem |
338 |
supports both of these, the former via the <tt>conn()</tt> routine and the |
339 |
latter via listener sockets. Outgoing connections are handled |
340 |
asynchronously, like all other socket operations, and the |
341 |
<tt>SCB_CONNECT</tt> callback is used to inform the caller when the |
342 |
connection has completed.</p> |
343 |
|
344 |
<p>Once a connection has been established, it can also be broken at either |
345 |
the local or the remote side. The socket subsystem provides the |
346 |
<tt>disconn()</tt> routine for deliberately closing a connection, and |
347 |
notifies the caller of a connection closed by the remote host through the |
348 |
<tt>SCB_DISCONNECT</tt> callback.</p> |
349 |
|
350 |
<p class="backlink"><a href="#top">Back to top</a></p> |
351 |
|
352 |
|
353 |
<h4 class="subsubsection-title" id="s3-1">3-3-1. Outgoing connections</h4> |
354 |
|
355 |
<p>To establish a connection to a remote host, the caller should first |
356 |
create a socket, configure it as appropriate (including, at minimum, the |
357 |
<tt>SCB_CONNECT</tt> and <tt>SCB_DISCONNECT</tt> callbacks), then call the |
358 |
<tt>conn()</tt> routine:</p> |
359 |
|
360 |
<div class="code">int <b>conn</b>(Socket *<i>s</i>, |
361 |
const char *<i>host</i>, int <i>port</i>, |
362 |
const char *<i>lhost</i>, int <i>lport</i>)</div> |
363 |
|
364 |
<p>This routine attempts to establish a TCP connection to the host |
365 |
specified by <tt><i>host</i></tt> on TCP port number <tt><i>port</i></tt>. |
366 |
The hostname may be specified as either a hostname, which is passed to the |
367 |
system's <tt>gethostbyname()</tt> address lookup function (if the call |
368 |
returns multiple addresses, the first one returned by the system will be |
369 |
used), or a numeric IPv4 address, which is parsed directly. The address to |
370 |
be used for the local side of the socket can also be specified with the |
371 |
<tt><i>lhost</i></tt> and <tt><i>lport</i></tt> parameters; values of |
372 |
<tt>NULL</tt> and zero, respectively, leave the choice of the corresponding |
373 |
parameter to the system.</p> |
374 |
|
375 |
<p>If an error is encountered in setting up the connection, such as an |
376 |
invalid host name or port number, the <tt>conn()</tt> routine returns -1 |
377 |
and sets <tt>errno</tt> appropriately; the value in <tt>errno</tt> may be |
378 |
negative, indicating a hostname resolution failure (pass the negative of |
379 |
this value to <tt>hstrerror()</tt> to obtain an error message string). |
380 |
Otherwise, the routine returns zero, signifying that the connection is in |
381 |
process.</p> |
382 |
|
383 |
<p>When the connection completes, the socket subsystem calls the socket's |
384 |
<tt>SCB_CONNECT</tt> callback function to notify the caller that the |
385 |
connection is ready for use. Alternatively, the connection may be refused |
386 |
by the remote host, in which case the socket's <tt>SCB_DISCONNECT</tt> |
387 |
callback is called with a parameter of <tt>DISCONN_CONNFAIL</tt>.</p> |
388 |
|
389 |
<p>Note that when a connection is made to the local host or a sufficiently |
390 |
close remote host, the connection may complete or be rejected immediately. |
391 |
If the connection is rejected, <tt>conn()</tt> will return an error, but if |
392 |
it is accepted, the <tt>SCB_CONNECT</tt> callback will be called |
393 |
immediately, before <tt>conn()</tt> returns; the caller must therefore |
394 |
perform all necessary setup for the callback function before calling |
395 |
<tt>conn()</tt>.</p> |
396 |
|
397 |
<p>Internally, <tt>conn()</tt> sets the <tt>SF_CONNECTING</tt> flag on the |
398 |
socket while the connection is being processed by the system; the socket |
399 |
polling routine then watches for the connection to complete or fail, |
400 |
setting the <tt>SF_CONNECTED</tt> flag in the former case and calling the |
401 |
appropriate callback. If the connection completes immediately, |
402 |
<tt>conn()</tt> itself sets the <tt>SF_CONNECTED</tt> flag.</p> |
403 |
|
404 |
<p class="backlink"><a href="#top">Back to top</a></p> |
405 |
|
406 |
|
407 |
<h4 class="subsubsection-title" id="s3-2">3-3-2. Incoming connections</h4> |
408 |
|
409 |
<p>In order to accept connections from remote hosts, a <i>listener |
410 |
socket</i>, which "listens" for connections on a specified port, must first |
411 |
be created. This is done with the <tt>open_listener()</tt> routine:</p> |
412 |
|
413 |
<div class="code">int <b>open_listener</b>(Socket *<i>s</i>, const char *<i>host</i>, |
414 |
int <i>port</i>, int <i>backlog</i>)</div> |
415 |
|
416 |
<p>This function turns the given socket into a listener socket which will |
417 |
accept connections on the given TCP port. If <tt><i>host</i></tt> is not |
418 |
<tt>NULL</tt>, connections will only be accepted on the corresponding IP |
419 |
address (processed the same way as for <tt>conn()</tt>—note in |
420 |
particular that if the hostname has multiple addresses associated with it, |
421 |
only one will be used). The <tt><i>backlog</i></tt> value is passed |
422 |
directly to the system's <tt>listen()</tt> function, and indicates how many |
423 |
connections the system should allow to be pending (recognized by the system |
424 |
but not yet accepted by the program).</p> |
425 |
|
426 |
<p>In order to actually accept connections, a function must be assigned to |
427 |
the socket's <tt>SCB_ACCEPT</tt> callback (if no function is assigned, any |
428 |
connections received by the socket will be dropped immediately). The |
429 |
<tt>void *</tt> parameter passed to this function is a new socket |
430 |
object that has been created for the connection, already connected to the |
431 |
remote host. The new socket is initialized in the same manner as sockets |
432 |
created with <tt>sock_new()</tt>, so the accept callback will need to |
433 |
configure the socket appropriately (setting callback functions and so on). |
434 |
The new socket can be used in the same manner as sockets explicitly created |
435 |
with <tt>sock_new()</tt>, except that the socket will be automatically |
436 |
destroyed when disconnected (thus the caller must be careful not to |
437 |
continue using the socket after the connection is closed).</p> |
438 |
|
439 |
<p>Internally, the <tt>SF_LISTENER</tt> flag is used to mark an active |
440 |
listener socket. When a read event occurs on such a socket, the |
441 |
<tt>do_accept()</tt> internal routine accepts the connection, creates a |
442 |
new socket object (with the <tt>SF_SELFCREATED</tt> flag set, to indicate |
443 |
that the socket was created internally rather than an external |
444 |
<tt>sock_new()</tt> call and should be destroyed upon disconnection), sets |
445 |
up the new socket with the accepted connection, and calls the listener |
446 |
socket's <tt>SCB_ACCEPT</tt> callback function.</p> |
447 |
|
448 |
<p class="backlink"><a href="#top">Back to top</a></p> |
449 |
|
450 |
|
451 |
<h4 class="subsubsection-title" id="s3-3">3-3-3. Disconnecting</h4> |
452 |
|
453 |
<p>When a connection is no longer needed, the <tt>disconn()</tt> routine |
454 |
can be called to disconnect a connected socket from the remote host:</p> |
455 |
|
456 |
<div class="code">void <b>disconn</b>(Socket *<i>s</i>)</div> |
457 |
|
458 |
<p>This routine first flushes the socket's write buffer if any unsent data |
459 |
remains, then calls the socket's <tt>SCB_DISCONNECT</tt> callback with a |
460 |
parameter of <tt>DISCONN_LOCAL</tt>. The return value is zero on success, |
461 |
-1 on error (such as an invalid or listener socket). If there is unsent |
462 |
data remaining in the write buffer and it cannot be immediately sent to the |
463 |
remote host, however, then <tt>disconn()</tt> will return successfully |
464 |
without calling the <tt>SCB_DISCONNECT</tt> callback; in this case, the |
465 |
callback will be called by the socket polling routine once all the data has |
466 |
been sent.</p> |
467 |
|
468 |
<p>A connection may also be closed by the remote host; in this case, the |
469 |
socket subsystem will automatically return the socket to an unconnected |
470 |
state, calling the <tt>SCB_DISCONNECT</tt> callback with a parameter of |
471 |
<tt>DISCONN_REMOTE</tt>. In this case, there is no point in attempting to |
472 |
send any data remaining in the write buffer, and it is simply discarded. |
473 |
If the disconnection is detected while a socket callback is being processed |
474 |
(for example, when an attempt to send data to the remote host fails), the |
475 |
disconnection will be postponed until the callback completes, so callback |
476 |
functions do not need to worry about checking the socket's status after |
477 |
every send operation.</p> |
478 |
|
479 |
<p>Listener sockets cannot be closed with <tt>disconn()</tt>; a separate |
480 |
function, <tt>close_listener()</tt>, is used to stop the socket from |
481 |
accepting new connections and return it to an unused (unconnected) state.</p> |
482 |
|
483 |
<p>Internally, disconnection is handled by the <tt>do_disconn()</tt> |
484 |
routine, which is called for all types of disconnections—local, |
485 |
remote, and connection failures—with the code appropriate to the |
486 |
disconnection reason. The code may be bitwise OR'd with |
487 |
<tt>DISCONN_RESUME_FLAG</tt>, a local flag (masked out before calling the |
488 |
disconnect callback) indicating that the call to <tt>do_disconn()</tt> is |
489 |
being made to continue a disconnection in progress. The routine performs |
490 |
the following operations:</p> |
491 |
|
492 |
<ul> |
493 |
<li class="spaced">Ensures that the socket pointer is not <tt>NULL</tt> and |
494 |
does not reference a listener socket, returning an error (-1 with |
495 |
<tt>EINVAL</tt>) in either case.</li> |
496 |
|
497 |
<li class="spaced">Checks whether the socket's <tt>SF_DISCONNECTING</tt> |
498 |
flag, indicating a disconnection operation in progress, is set. If |
499 |
the flag is set and the <tt>DISCONN_RESUME_FLAG</tt> flag is not |
500 |
set in the disconnection code, the disconnection request is ignored |
501 |
and success (zero) is returned.</li> |
502 |
|
503 |
<li class="spaced">Checks whether the socket's <tt>SF_DISCONN_REQ</tt> |
504 |
flag, indicating a disconnection request in progress, is set. If |
505 |
so, and if the disconnection code is <tt>DISCONN_LOCAL</tt>, the |
506 |
request is ignored. (Remote disconnects and connection failures |
507 |
are passed through, overriding local disconnects, so that if a |
508 |
remote disconnect is detected while <tt>disconn()</tt> is flushing |
509 |
the write buffer, for example, the disconnect callback will see the |
510 |
code <tt>DISCONN_REMOTE</tt> rather than <tt>DISCONN_LOCAL</tt>.</li> |
511 |
|
512 |
<li class="spaced">Checks the socket's <tt>SF_CONNECTING</tt> and |
513 |
<tt>SF_CONNECTED</tt> flags. If neither flag is set, the socket is |
514 |
not connected, so there is nothing to do, and the request is |
515 |
ignored.</li> |
516 |
|
517 |
<li class="spaced">Sets the socket's <tt>SF_DISCONN_REQ</tt> flag.</li> |
518 |
|
519 |
<li class="spaced">Clears the socket's file descriptor from the set of |
520 |
descriptors to check for read status (see <a href="#s6">section |
521 |
3-6</a>).</li> |
522 |
|
523 |
<li class="spaced">If the disconnection code is <tt>DISCONN_LOCAL</tt> and |
524 |
there is unsent data in the write buffer, calls |
525 |
<tt>flush_write_buffer()</tt> (see <a href="#s4-1">section |
526 |
3-4-1</a>) to send the data out. If the data cannot be sent |
527 |
immediately, the socket's <tt>SF_DISCONNECT</tt> flag is set, and |
528 |
success is returned; <tt>do_disconn()</tt> must be called again by |
529 |
the socket polling routine with the <tt>DISCONN_RESUME_FLAG</tt> |
530 |
flag set in the code once all data has been sent.</li> |
531 |
|
532 |
<li class="spaced">Sets the socket's <tt>SF_DISCONNECTING</tt> flag.</li> |
533 |
|
534 |
<li class="spaced">Shuts down communications on the socket at the system |
535 |
level, by calling <tt>shutdown()</tt> and <tt>close()</tt>. (The |
536 |
actual closing of the file descriptor is handled by |
537 |
<tt>sock_closefd()</tt>, an internal routine that takes care of |
538 |
clearing socket object fields and file descriptor set bits |
539 |
appropriately.)</li> |
540 |
|
541 |
<li class="spaced">Clears out the socket's write map list (ses |
542 |
<a href="#s4-1">section 3-4-1</a>).</li> |
543 |
|
544 |
<li class="spaced">Calls the socket's <tt>SCB_DISCONNECT</tt> callback |
545 |
function, if one is set, passing the disconnection code with the |
546 |
<tt>DISCONN_RESUME_FLAG</tt> internal flag cleared.</li> |
547 |
|
548 |
<li class="spaced">Clears the socket's <tt>SF_DISCONNECTING</tt> flag.</li> |
549 |
|
550 |
<li class="spaced">If the socket's file descriptor is no longer unset |
551 |
(meaning that the disconnect callback function reconnected the |
552 |
socket), aborts further processing and returns success.</li> |
553 |
|
554 |
<li class="spaced">Clears the socket's <tt>SF_CONNECTING</tt> and |
555 |
<tt>SF_CONNECTED</tt> flags.</li> |
556 |
|
557 |
<li class="spaced">If the socket's <tt>SF_SELFCREATED</tt> flag, indicating |
558 |
a socket created by accepting a connection, or <tt>SF_DELETEME</tt> |
559 |
flag, indicating a delayed destroy operation, is set, destroys the |
560 |
socket; otherwise frees all buffer space used by the socket.</li> |
561 |
</ul> |
562 |
|
563 |
<p>Note that the values used for the disconnection codes do not include |
564 |
zero; this is to avoid unexpected consequences when the value is |
565 |
converted to a pointer for use as the <tt>void *</tt> argument |
566 |
to the callback function. (Theoretically, conversions both ways |
567 |
should handle the zero and <tt>NULL</tt> values appropriately, but |
568 |
there's always the possibility of a broken compiler |
569 |
. . .)</p> |
570 |
|
571 |
<p class="backlink"><a href="#top">Back to top</a></p> |
572 |
|
573 |
<!------------------------------------------------------------------------> |
574 |
<hr/> |
575 |
|
576 |
<h3 class="subsection-title" id="s4">3-4. Sending and receiving data</h3> |
577 |
|
578 |
<p>The socket subsystem includes several routines for sending data to and |
579 |
receiving data from remote systems, which more or less mimic the standard |
580 |
system and library functions for reading and writing data. These routines |
581 |
never block, however; send operations store the given data in the socket's |
582 |
write buffer and return immediately (with the exception discussed under |
583 |
<tt>sock_set_blocking()</tt> in <a href="#s2-1">section 3-2-1</a>), while |
584 |
receive operations return an end-of-file condition if there is not enough |
585 |
data in the read buffer to satisfy the operation.</p> |
586 |
|
587 |
<p class="backlink"><a href="#top">Back to top</a></p> |
588 |
|
589 |
|
590 |
<h4 class="subsubsection-title" id="s4-1">3-4-1. Sending data</h4> |
591 |
|
592 |
<p>There are two main families of data sending routines: string-based |
593 |
(stdio-like) routines and buffer-based routines. The interfaces are as |
594 |
follows:</p> |
595 |
|
596 |
<dl> |
597 |
<dt><tt>int <b>sputs</b>(const char *<i>str</i>, Socket *<i>s</i>)</tt></dt> |
598 |
<dd>Sends the given null-terminated string to the given socket, like |
599 |
<tt>fputs()</tt>. (Does <i>not</i> write a trailing newline.) |
600 |
Returns the number of bytes written, or -1 on failure.</dd> |
601 |
|
602 |
<dt><tt>int <b>sockprintf</b>(Socket *<i>s</i>, const char *<i>fmt</i>, ...)</tt> |
603 |
<br/><tt>int <b>vsockprintf</b>(Socket *<i>s</i>, const char *<i>fmt</i>, va_list <i>args</i></tt></dt> |
604 |
<dd>Formats the variadic argument list according to the format string |
605 |
<tt><i>fmt</i></tt> and sends it to the given socket, like |
606 |
<tt>fprintf()</tt>. Returns the number of bytes written, or -1 on |
607 |
failure.</dd> |
608 |
|
609 |
<dt><tt>int32 <b>swrite</b>(Socket *<i>s</i>, const char *<i>buf</i>, int32 <i>len</i>)</tt></dt> |
610 |
<dd>Sends data from buffer <tt><i>buf</i></tt> of length |
611 |
<tt><i>len</i></tt> to the given socket, like <tt>write()</tt>. |
612 |
Returns the number of bytes written, or -1 on failure.</dd> |
613 |
|
614 |
<dt><tt>int32 <b>swritemap</b>(Socket *<i>s</i>, const char *<i>buf</i>, int32 <i>len</i>)</tt></dt> |
615 |
<dd>Sends data to the given socket, like <tt>swrite()</tt>; the buffer |
616 |
<tt><i>buf</i></tt> is taken to be a region of memory (of length |
617 |
<tt><i>len</i></tt>) mapped with <tt>mmap()</tt>, and will be freed |
618 |
automatically with <tt>munmap()</tt> when all of the data has been |
619 |
sent to the socket. If <tt>DISABLE_SWRITEMAP</tt> (see |
620 |
<a href="#s1">section 3-1</a>) is defined, returns the error |
621 |
<tt>ENOSYS</tt>.</dd> |
622 |
|
623 |
<dt><tt>int <b>swrite_trigger</b>(Socket *<i>s</i>, void *<i>data</i>)</tt></dt> |
624 |
<dd>Inserts a <i>write trigger</i> at the socket's current write buffer |
625 |
position, causing the socket's <tt>SCB_TRIGGER</tt> callback |
626 |
function to be called when all data written prior to the |
627 |
<tt>swrite_trigger()</tt> call has been successfully sent to the |
628 |
remote host, and before any data written subsequently has been |
629 |
sent. The value passed as the <tt><i>data</i></tt> parameter is |
630 |
passed on unmodified to the callback function.</dd> |
631 |
</dl> |
632 |
|
633 |
<p>The first three functions perform the actual writing using the internal |
634 |
<tt>buffered_write()</tt> routine. This function first resets the |
635 |
timestamp used for detecting send timeouts if there is no data waiting to |
636 |
be sent (either in the write buffer or in mapped buffers, as described |
637 |
below), then copies the caller's data into the socket's write buffer up to |
638 |
the current buffer size and calls the <tt>flush_write_buffer()</tt> routine |
639 |
to send out any buffered data that can be sent without blocking; these two |
640 |
steps are repeated until all of the caller's data has been buffered (and |
641 |
possibly sent).</p> |
642 |
|
643 |
<p>The <tt>flush_write_buffer()</tt> routine, in turn, first checks for |
644 |
mapped write buffers and write triggers, as described below, then calls the |
645 |
system's <tt>send()</tt> function to send a single contiguous block of data |
646 |
to the remote host. The data actually sent (which may be none at all, if |
647 |
the system is not ready to accept any more data for the socket) is removed |
648 |
from the write buffer, and the number of bytes sent is returned. The |
649 |
routine returns -1 on system error (or invalid parameter), and -2 if the |
650 |
socket was in the middle of a disconnect and there is no more data to |
651 |
send. <tt>flush_write_buffer()</tt> also manages the set of file |
652 |
descriptors to watch for write-ready events, used in the polling routine, |
653 |
and shrinks the socket's buffers if a send operation removes all pending |
654 |
data from the write buffer.</p> |
655 |
|
656 |
<p>If an attempt to flush the write buffer fails when the buffer is full, |
657 |
<tt>buffered_write()</tt> attempts to expand the buffer. This is done by |
658 |
calling <tt>resize_how_much()</tt> to find out how much the buffer should |
659 |
be expanded by (the current implementation uses a constant 10%, rounded up |
660 |
to the next multiple of <tt>SOCK_MIN_BUFSIZE</tt>), then performs the actual |
661 |
resize operation. If <tt>resize_how_much()</tt> returns zero, meaning that |
662 |
trying to expand the buffer would exceed the per-connection or total buffer |
663 |
size limit, or if the attempt to resize the buffer fails, then |
664 |
<tt>buffered_write()</tt> either returns an <tt>EAGAIN</tt> error or blocks |
665 |
until some buffer space can be freed, depending on whether the socket has |
666 |
been set blocking via <tt>sock_set_blocking()</tt> or not.</p> |
667 |
|
668 |
<p>In order to avoid the overhead of moving data around on every send |
669 |
operation, the write buffer is used circularly, through the use of four |
670 |
pointers in the <tt>Socket</tt> structure:</p> |
671 |
<ul> |
672 |
<li><b><tt>wbuf</tt>:</b> Points to the base address of the buffer.</li> |
673 |
<li><b><tt>wptr</tt>:</b> Points to the first byte of valid data in the |
674 |
buffer.</li> |
675 |
<li><b><tt>wend</tt>:</b> Points to the first byte after the last byte of |
676 |
valid data in the buffer.</li> |
677 |
<li><b><tt>wtop</tt>:</b> Points to one byte beyond the last byte of the |
678 |
buffer (for convenience).</li> |
679 |
</ul> |
680 |
|
681 |
<p>The <tt>wbuf</tt> and <tt>wtop</tt> pointers remain constant (except for |
682 |
changes in the location or size of the buffer itself) for the life of the |
683 |
socket, while the <tt>wptr</tt> and <tt>wend</tt> pointers advance |
684 |
circularly through the buffer space as data is added and removed. The |
685 |
amount of data in the buffer can be computed as |
686 |
<tt>wend - wptr</tt>, modulo the buffer size; note that this |
687 |
difference will be negative if <tt>wend</tt> has wrapped around to the |
688 |
beginning of the buffer but <tt>wptr</tt> has not, so the buffer size |
689 |
(<tt>wtop - wbuf</tt>) must be added to the result, as is done |
690 |
in the <tt>write_buffer_len()</tt> function. Thus an empty buffer is |
691 |
indicated by <tt>wend == wptr</tt>, while a full buffer is |
692 |
indicated by <tt>wend == wptr-1</tt> (again, modulo the buffer |
693 |
size), leaving a one-byte pad to avoid a full buffer being mistakenly |
694 |
treated as an empty one.</p> |
695 |
|
696 |
<p>The last two functions for sending data, <tt>swritemap()</tt> and |
697 |
<tt>swrite_trigget()</tt>, record their data in the <i>write-map list</i>, |
698 |
a singly-linked list of structures containing information on mapped buffers |
699 |
and write triggers. The structure is <tt>struct wmapinfo</tt>, defined |
700 |
within the <tt>Socket</tt> structure definition in <tt>sockets.c</tt>, and |
701 |
contains the following fields:</p> |
702 |
|
703 |
<ul> |
704 |
<li><b><tt>next</tt>:</b> A pointer to the next structure in the list.</li> |
705 |
<li><b><tt>wait</tt>:</b> The number of bytes left to send from the write |
706 |
buffer before processing this structure.</li> |
707 |
<li><b><tt>map</tt>, <tt>maplen</tt>:</b> The buffer pointer and buffer |
708 |
length (for write triggers, the data for the callback function and |
709 |
zero).</li> |
710 |
<li><b><tt>pos</tt>:</b> The current position within the buffer (the number |
711 |
of bytes sent from the buffer so far).</li> |
712 |
</ul> |
713 |
|
714 |
<p>The head of the list is stored in the <tt>writemap</tt> field of the |
715 |
socket object; the tail of the list is also recorded in the |
716 |
<tt>writemap_tail</tt> field for efficiency reasons. If the list is empty, |
717 |
both fields are <tt>NULL</tt>.</p> |
718 |
|
719 |
<p>When <tt>swritemap()</tt> or <tt>swrite_trigger()</tt> is called, a new |
720 |
structure is created and appended to the list, with the <tt>map</tt> and |
721 |
<tt>maplen</tt> fields set to the buffer pointer and length (or the trigger |
722 |
data and zero), the <tt>pos</tt> field set to zero, and the <tt>wait</tt> |
723 |
field set to the current length of the write buffer. The |
724 |
<tt>flush_write_buffer()</tt> then checks at the beginning of the routine |
725 |
whether the first write-map structure (if one exists) is ready for |
726 |
processing (has a <tt>wait</tt> value of zero). If so, data is sent from |
727 |
the mapped buffer instead of the socket's write buffer; in the case of a |
728 |
write trigger, the <tt>SF_WTRIGGER</tt> flag is set, to cause the polling |
729 |
routine to call the socket's write trigger callback function and to prevent |
730 |
any further buffer flushes from occurring before then. Otherwise, data is |
731 |
sent from the socket's write buffer as usual, and every write-map |
732 |
structure's <tt>wait</tt> field is decremented by the number of bytes sent. |
733 |
<i>Implementation note: This roundabout method is a result of adding the |
734 |
<tt>swritemap()</tt> and <tt>swrite_trigger()</tt> fields after the initial |
735 |
socket subsystem design was complete (in fact, Services does not use them |
736 |
at all—I added them for my HTTP server). A more intelligent design |
737 |
would use a write-map or similar structure for every block of data to be |
738 |
sent, possibly pointing into a common buffer like the current write |
739 |
buffer.</i></p> |
740 |
|
741 |
<p class="backlink"><a href="#top">Back to top</a></p> |
742 |
|
743 |
|
744 |
<h4 class="subsubsection-title" id="s4-2">3-4-2. Receiving data</h4> |
745 |
|
746 |
<p>Like send operations, there are two main groups of receive routines, |
747 |
string- (or character-) based and buffer-based:</p> |
748 |
|
749 |
<dl> |
750 |
<dt><tt>int <b>sgetc</b>(Socket *<i>s</i>)</tt></dt> |
751 |
<dd>Reads a single byte (character) from the socket, returning the |
752 |
value of the byte read or <tt>EOF</tt> if no data is available. |
753 |
Assumes the socket passed in is valid.</dd> |
754 |
|
755 |
<dt><tt>int <b>sgets</b>(char *<i>buf</i>, int32 <i>len</i>, Socket *<i>s</i>)</tt></dt> |
756 |
<dd>Reads a line of data (ending with an LF character, value 0x0A) from |
757 |
the given socket, storing it in <tt><i>buf</i></tt>. If the string |
758 |
(including the null terminator) requires more than <tt><i>len</i></tt> |
759 |
bytes, it is truncated to <tt><i>len</i>-1</tt> bytes, but the |
760 |
entire string (to the newline) is removed from the socket'S buffer. |
761 |
Returns <tt><i>buf</i></tt>, or <tt>NULL</tt> if no complete line |
762 |
is available to read or an error occurs.</dd> |
763 |
|
764 |
<dt><tt>int <b>sgets2</b>(char *<i>buf</i>, int32 <i>len</i>, Socket *<i>s</i>)</tt></dt> |
765 |
<dd>Reads a line of data from the given socket and stores it in |
766 |
<tt><i>buf</i></tt>, like <tt>sgets()</tt>; however, a trailing |
767 |
LF or CR/LF pair will be stripped from the string before it is |
768 |
returned.</dd> |
769 |
|
770 |
<dt><tt>int <b>sread</b>(Socket *<i>s</i>, char *<i>buf</i>, int32 <i>len</i>)</tt></dt> |
771 |
<dd>Reads a block of data from the socket, returning the number of |
772 |
bytes successfully read (which may be less than <tt><i>len</i></tt>, |
773 |
or zero, if insufficient data is available in the socket's |
774 |
buffer to satisfy the requsst). Returns -1 on error.</dd> |
775 |
</dl> |
776 |
|
777 |
<p>All four of these functions operate on the socket's read buffer. This |
778 |
buffer is filled by the socket polling routine (see <a href="#s6">section |
779 |
3-6</a>) when data has been received by the system and is available for |
780 |
reading from the socket. The routines are intended to be called from the |
781 |
<tt>SCB_READ</tt> or <tt>SCB_READLINE</tt> callbacks, which are called by |
782 |
the polling routine when data is available.</p> |
783 |
|
784 |
<p>The use of two distinct callbacks for reading data is to facilitate the |
785 |
processing of both binary and textual data. When data has been received on |
786 |
the socket's connection and stored in the buffer, the socket subsystem |
787 |
first calls the <tt>SCB_READ</tt> callback function, passing the number of |
788 |
bytes available for reading (an integer value, cast to <tt>void *</tt> |
789 |
for the call). If the callback function leaves some data in the buffer (or |
790 |
no function is assigned), and if at least one newline character is present |
791 |
in the buffer, the <tt>SCB_READLINE</tt> callback function is then called, |
792 |
again with the number of bytes available for reading. If there is still |
793 |
data left in the buffer, both callbacks are called again in order, |
794 |
repeating until either all data has been consumed or the |
795 |
<tt>SCB_READ</tt>/<tt>SCB_READLINE</tt> pair does not read any data from |
796 |
the socket's buffer.</p> |
797 |
|
798 |
<p>The read buffer is handled in the same manner as the write buffer; four |
799 |
fields (<tt><i>rbuf</i></tt>, <tt><i>rptr</i></tt>, <tt><i>rend</i></tt>, |
800 |
and <tt><i>rtop</i></tt>) are used to manage data insertion and removal, |
801 |
and like the write buffer, the read buffer is used circularly to avoid |
802 |
overhead from moving data around.</p> |
803 |
|
804 |
<p class="backlink"><a href="#top">Back to top</a></p> |
805 |
|
806 |
|
807 |
<h4 class="subsubsection-title" id="s4-3">3-4-3. Muting sockets</h4> |
808 |
|
809 |
<p>If the caller does not want to receive socket events for a certain |
810 |
socket, the socket can be <i>muted</i>. The socket subsystem will not |
811 |
attempt to receive any data from the remote host for a muted socket, and |
812 |
will not call the <tt>SCB_READ</tt> or <tt>SCB_READLINE</tt> callbacks. |
813 |
Listener sockets can also be muted, causing the socket subsystem to not |
814 |
accept any connections from remote hosts or call the <tt>SCB_ACCEPT</tt> |
815 |
callback (connection attempts will be left waiting in the operating |
816 |
system's queue). Note that muting a socket does not have any effect on the |
817 |
operating system's low-level data processing; if the OS automatically |
818 |
accepts connection attempts at the protocol level, for example, the remote |
819 |
host will still see the connection established. Also note that a socket in |
820 |
the process of connecting or disconnecting will still call the |
821 |
<tt>SCB_CONNECT</tt> or <tt>SCB_DISCONNECT</tt> callback when the operation |
822 |
completes, and the write buffer will still be flushed normally, causing the |
823 |
<tt>SCB_TRIGGER</tt> callback to be called if a write trigger is |
824 |
encountered.</p> |
825 |
|
826 |
<p>The functions for muting and unmuting sockets are:</p> |
827 |
|
828 |
<dl> |
829 |
<dt><tt>void <b>sock_mute</b>(Socket *<i>s</i>)</tt></dt> |
830 |
<dd>Mutes the given socket, disabling all read and accept events. |
831 |
Does nothing if the socket was already muted.</dd> |
832 |
|
833 |
<dt><tt>void <b>sock_unmute</b>(Socket *<i>s</i>)</tt></dt> |
834 |
<dd>Unmutes the given socket, allowing read and accept events to occur. |
835 |
Does nothing if the socket was not muted. If any data is present |
836 |
in the socket's read buffer, the <tt>SCB_READ</tt> and |
837 |
<tt>SCB_READLINE</tt> callbacks will be called once regardless of |
838 |
whether any new data has arrived on the socket.</dd> |
839 |
</dl> |
840 |
|
841 |
|
842 |
<p class="backlink"><a href="#top">Back to top</a></p> |
843 |
|
844 |
<!------------------------------------------------------------------------> |
845 |
<hr/> |
846 |
|
847 |
<h3 class="subsection-title" id="s5">3-5. Retrieving socket information</h3> |
848 |
|
849 |
<p>The following routines can be used to retrieve information on sockets:</p> |
850 |
|
851 |
<dl> |
852 |
<dt><tt>int <b>sock_isconn</b>(const Socket *<i>s</i>)</tt></dt> |
853 |
<dd>Returns whether the socket is currently connected to a remote |
854 |
host (nonzero if connected, else zero).</dd> |
855 |
|
856 |
<dt><tt>int <b>sock_remote</b>(const Socket *<i>s</i>, struct sockaddr *<i>sa</i>, |
857 |
int *<i>lenptr</i>)</tt></dt> |
858 |
<dd>Retrieves the remote host's address if the socket is connected, |
859 |
returning 0 on success, -1 on failure. Equivalent to the system |
860 |
call <tt>getpeername()</tt> on ordinary sockets.</dd> |
861 |
|
862 |
<dt><tt>int <b>sock_get_blocking</b>(const Socket *<i>s</i>)</tt></dt> |
863 |
<dd>Returns whether the given socket is in blocking mode or not. |
864 |
The return value is positive if the socket is in blocking mode, |
865 |
zero if it is in non-blocking mode, or -1 if the socket parameter |
866 |
is invalid.</dd> |
867 |
|
868 |
<dt><tt>uint32 <b>read_buffer_len</b>(const Socket *<i>s</i>)</tt> |
869 |
<br/><tt>uint32 <b>write_buffer_len</b>(const Socket *<i>s</i>)</tt></dt> |
870 |
<dd>Returns the given socket's read or write buffer length (the |
871 |
amount of data received but not processed, or buffered but not |
872 |
yet sent, respectively), in bytes. The socket parameter must |
873 |
point to a valid socket (it is not checked for validity).</dd> |
874 |
|
875 |
<dt><tt>uint32 <b>sock_rwstat</b>(const Socket *<i>s</i>, |
876 |
uint64 *<i>read_ret</i>, uint64 *<i>written_ret</i>)</tt></dt> |
877 |
<dd>Returns the amount of data received and sent on the given socket. |
878 |
The amount of data received is stored in the location pointed to by |
879 |
<tt><i>read_ret</i></tt>, and the amount sent is stored in the |
880 |
location pointed to by <tt><i>write_ret</i></tt>, both in bytes; |
881 |
the amount of data sent does not include data stored in the write |
882 |
buffer but not yet sent to the remote host. Either pointer can be |
883 |
<tt>NULL</tt> if the corresponding value is not needed. The |
884 |
routine returns 0 on success, -1 on failure.</dd> |
885 |
|
886 |
<dt><tt>int <b>sock_bufstat</b>(const Socket *<i>s</i>, |
887 |
uint32 *<i>socksize_ret</i>, uint32 *<i>totalsize_ret</i>, |
888 |
int *<i>ratio1_ret</i>, int *<i>ratio2_ret</i>)</tt></dt> |
889 |
<dd>Returns buffer size information about the given socket (if not |
890 |
<tt>NULL</tt>) and about the socket subsystem as a whole. |
891 |
<tt><i>socksize_ret</i></tt> is set to the number of bytes |
892 |
allocated for the given socket's read and write buffers, and |
893 |
<tt><i>ratio1_ret</i></tt> is set to the ratio of this value to |
894 |
the per-socket buffer size limit set with |
895 |
<tt>sock_set_buflimits()</tt>, expressed as a percentage rounded up |
896 |
to the nearest integer; if a <tt>NULL</tt> value is passed for the |
897 |
socket, <tt><i>socksize_ret</i></tt> will be left unmodified, and |
898 |
<tt><i>ratio1_ret</i></tt> will be set to zero. Likewise, |
899 |
<tt><i>totalsize_ret</i></tt> is set to the total number of bytes |
900 |
allocated for socket buffers, and <tt><i>ratio2_ret</i></tt> is set |
901 |
to the percentage ratio of this value to the total buffer size |
902 |
limit. The function's return value is the larger of the two ratios |
903 |
given above, also as a percentage. If the per-socket or total |
904 |
buffer size limit is disabled, the corresponding ratio will be set |
905 |
to zero. Any of the return talue parameters can be set to |
906 |
<tt>NULL</tt>, in which case the corresponding value will not be |
907 |
returned.</dd> |
908 |
</dl> |
909 |
|
910 |
<p class="backlink"><a href="#top">Back to top</a></p> |
911 |
|
912 |
<!------------------------------------------------------------------------> |
913 |
<hr/> |
914 |
|
915 |
<h3 class="subsection-title" id="s6">3-6. The socket polling routine</h3> |
916 |
|
917 |
<p>The final socket interface routine, <tt>check_sockets()</tt>, is the |
918 |
workhorse of the socket subsystem. The routine waits for activity to |
919 |
occur, reading data from any sockets on which new data has been received, |
920 |
flushing the write buffer when a socket becomes ready for sending more |
921 |
data, and accepting connections from listener sockets on which a new |
922 |
connection request is received. If a timeout has been set with |
923 |
<tt>sock_set_rto()</tt> (see <a href="#s2-1">section 3-2-1</a>), the |
924 |
routine returns control to the caller if no activity occurs within that |
925 |
time (the name "rto", for "read timeout", is something of a misnomer, since |
926 |
it applies to all types of activity: read-ready, write-ready, and new |
927 |
connection).</p> |
928 |
|
929 |
<p>When called, <tt>check_sockets()</tt> first sets up the file descriptor |
930 |
sets and timeout value used in the <tt>select()</tt> system call (the file |
931 |
descriptor sets are actually initialized and modified by other routines as |
932 |
appropriate; <tt>check_sockets()</tt> makes a copy of them so the originals |
933 |
are not modified by <tt>select()</tt>. The timeout is ordinarily the value |
934 |
given to <tt>sock_set_rto()</tt>, but if one or more sockets with a write |
935 |
timeout set has data pending in the write buffer, the timeout is reduced to |
936 |
the time until the earliest timeout (with second resolution). Then |
937 |
<tt>select()</tt> is invoked; signals are enabled only for the duration of |
938 |
the <tt>select()</tt> call, and disabled immediately after |
939 |
<tt>select()</tt> returns. (It is assumed that signals are disabled when |
940 |
<tt>check_sockets()</tt> is called; <tt>init_signals()</tt> disables |
941 |
signals before it returns, so this prerequisite is fulfulled.) The |
942 |
<tt>select()</tt> call is made in a loop to ensure that a received signal |
943 |
is not interpreted as an error.</p> |
944 |
|
945 |
<p>After <tt>select()</tt> returns (and if it does not return an error), |
946 |
<tt>check_sockets()</tt> then loops through each file descriptor used in |
947 |
the <tt>select()</tt> call. The <tt>Socket</tt> structure corresponding to |
948 |
each file descriptor is found from the <tt>sockets[]</tt> array, maintained |
949 |
separately from the linked list of sockets for this purpose.</p> |
950 |
|
951 |
<p>A write-ready event on a socket indicates either that a deferred |
952 |
connection has completed or failed, or that a connected socket has is ready |
953 |
to accept data for sending. In the latter case, <tt>check_sockets()</tt> |
954 |
simply calls <tt>flush_write_buffer()</tt> to send data out; |
955 |
<tt>flush_write_buffer()</tt> takes care of removing the file descriptor |
956 |
from the set to check for write-ready events if all data is flushed from |
957 |
the socket's write buffer. In the former case, <tt>check_sockets()</tt> |
958 |
retrieves the value of the socket's <tt>SO_ERROR</tt> option, which |
959 |
indicates the status of the connection attempt. A value of zero indicates |
960 |
success, while nonzero is an <tt>errno</tt>-style error number; the |
961 |
appropriate callback (<tt>SCB_CONNECT</tt> or <tt>SCB_DISCONNECT</tt>) is |
962 |
called, the socket's descriptor is removed from the write-ready set, and if |
963 |
the connection was successful and the socket is not muted, the descriptor |
964 |
is then added to the read-ready set so that it is checked on the next call |
965 |
to <tt>check_sockets()</tt>.</p> |
966 |
|
967 |
<p>After processing any write-ready event for a socket, the socket is |
968 |
checked for write trigger events as indicated by the <tt>SF_WTRIGGER</tt> |
969 |
socket flag, and if the flag is set, the <tt>SCB_TRIGGER</tt> is called |
970 |
repeatedly until the flag is no longer set. (The flag is cleared before |
971 |
each call to the callback function, but the callback function may set a new |
972 |
write trigger which is triggered before the function returns.)</p> |
973 |
|
974 |
<p>A read-ready event on a socket indicates either that a connected socket |
975 |
has received data or a disconnection event, or that a listener socket |
976 |
received a connection request. The latter case is simple; |
977 |
<tt>check_sockets()</tt> calls <tt>do_accept()</tt> to accept the |
978 |
connection, then proceeds to the next file descriptor. In the former case, |
979 |
the read buffer is first expanded if it is currently full, then |
980 |
<tt>fill_read_buffer()</tt> is called to actually receive data from the |
981 |
socket into the read buffer. <tt>fill_read_buffer()</tt> returns the |
982 |
number of bytes read from the socket, or -1 on error, in which case the |
983 |
socket is disconnected with the <tt>DISCONN_REMOTE</tt> code. |
984 |
<i>Implementation note: As documented in the code, if data arrives on a |
985 |
connection but the socket's read buffer is full and has reached the |
986 |
per-socket or total buffer size limit, the data will be left alone, causing |
987 |
<tt>select()</tt> to return immediately the next time it is called; this |
988 |
results in the program "busy-waiting" until either data is removed from the |
989 |
read buffer or space is made available to expand the buffer.</i></p> |
990 |
|
991 |
<p>After reading data from the socket, <tt>check_sockets()</tt> calls the |
992 |
<tt>SCB_READ</tt> and <tt>SCB_READLINE</tt> callbacks in turn, as described |
993 |
in <a href="#s4-2">section 3-4-2</a>. Even if the socket was not returned |
994 |
in the read-ready set from <tt>select()</tt>, the callbacks are still |
995 |
called if the <tt>SF_UNMUTED</tt> flag is set; this flag is set by |
996 |
<tt>sock_unmute()</tt> to indicate that a socket has just been unmuted, and |
997 |
cleared by <tt>check_sockets()</tt> before calling the read callbacks.</p> |
998 |
|
999 |
<p>Finally, <tt>check_sockets()</tt> checks whether a write timeout has |
1000 |
occurred on sockets that have a timeout set. If so, the socket is |
1001 |
disconnected with the <tt>DISCONN_REMOTE</tt> code, on the assumption that |
1002 |
the remote host is no longer reachable.</p> |
1003 |
|
1004 |
<p class="backlink"><a href="#top">Back to top</a></p> |
1005 |
|
1006 |
<!------------------------------------------------------------------------> |
1007 |
<hr/> |
1008 |
|
1009 |
<p class="backlink"><a href="2.html">Previous section: Core Services functionality</a> | |
1010 |
<a href="index.html">Table of Contents</a> | |
1011 |
<a href="4.html">Next section: The module system</a></p> |
1012 |
|
1013 |
</body> |
1014 |
</html> |