ViewVC Help
View File | Revision Log | Show Annotations | View Changeset | Root Listing
root/svn/vendor/ircservices-5.1.24/docs/tech/3.html
Revision: 3389
Committed: Fri Apr 25 14:12:15 2014 UTC (9 years, 10 months ago) by michael
Content type: text/html
File size: 53325 byte(s)
Log Message:
- Imported ircservices-5.1.24

File Contents

# Content
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/>&nbsp;&nbsp;&nbsp;&nbsp;3-2-1. <a href="#s2-1">Interface routines</a>
19 <br/>&nbsp;&nbsp;&nbsp;&nbsp;3-2-2. <a href="#s2-2">Socket callbacks</a>
20 <br/>3-3. <a href="#s3">Establishing and breaking connections</a>
21 <br/>&nbsp;&nbsp;&nbsp;&nbsp;3-3-1. <a href="#s3-1">Outgoing connections</a>
22 <br/>&nbsp;&nbsp;&nbsp;&nbsp;3-3-2. <a href="#s3-2">Incoming connections</a>
23 <br/>&nbsp;&nbsp;&nbsp;&nbsp;3-3-3. <a href="#s3-2">Disconnecting</a>
24 <br/>3-4. <a href="#s4">Sending and receiving data</a>
25 <br/>&nbsp;&nbsp;&nbsp;&nbsp;3-4-1. <a href="#s4-1">Sending data</a>
26 <br/>&nbsp;&nbsp;&nbsp;&nbsp;3-4-2. <a href="#s4-2">Receiving data</a>
27 <br/>&nbsp;&nbsp;&nbsp;&nbsp;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&nbsp;*</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&nbsp;*</tt> parameter indicating the socket on which
244 the event occured, and a <tt>void&nbsp;*</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&nbsp;*</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&nbsp;*</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&nbsp;*</tt> parameter is the newly-created socket (of type
285 <tt>Socket&nbsp;*</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&nbsp;*</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&nbsp;*</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>&mdash;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&nbsp;*</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&mdash;local,
485 remote, and connection failures&mdash;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&nbsp;*</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 .&nbsp;.&nbsp;.)</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&nbsp;-&nbsp;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&nbsp;-&nbsp;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&nbsp;==&nbsp;wptr</tt>, while a full buffer is
692 indicated by <tt>wend&nbsp;==&nbsp;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&mdash;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&nbsp;*</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>