1 Overview of the network subsystem
2 Adrian Chadd <adrian@creative.net.au>
6 This document is an overview of the new and hopefully improved network
9 The code is based loosely upon the network core found in the Squid web cache
10 server, with some optimizations for ircd-specific IO patterns.
17 Filedescriptor IO is initiated using comm_setselect(). comm_setselect()
18 registers interest in reading from or writing to a file descriptor.
19 When a filedescriptor is ready for the required IO a callback is called
22 The comm_setselect() usage is:
25 comm_setselect(int fd, fdlist_t list, int type, PF *callback, void *cbdata,
30 list Which list the FD should be put on
31 type IO type. Can currently include:
32 COMM_SELECT_READ - register for read
33 COMM_SELECT_WRITE - register for write
34 callback Function to call when the FD is ready
35 cbdata Data to be passed to above function
36 timeout Update the timeout value. 0 is "don't update".
43 /* Register interest in the FD for a read event */
44 comm_setselect(fd, FDLIST_SERVICE, COMM_SELECT_READ, read_callback, read_data,
49 (FD becomes ready for read in the IO loop)
52 read_callback(int fd, void *data)
54 /* called when the FD becomes ready for read */
55 retval = read(fd, buf, len);
58 /* Ok, we need to read some more when its ready */
59 comm_setselect(fd, FDLIST_SERVICE, COMM_SELECT_READ, read_callback, data,
69 A "socket timeout" is a callback registered to be called when a certain
70 amount of time has elapsed. Think of it as an event, but against a FD.
72 A good example of socket timeouts is in the comm_connect_tcp() code.
73 When the connect() begins, comm_settimeout() is called to call
74 comm_connect_timeout() if the timeout occurs. Once the connect() completes,
75 comm_settimeout() is called with a timeout of 0 and callback of NULL
76 to deregister the timeout. If the timeout occurs, comm_connect_timeout()
77 is called and the connection attempt is aborted.
85 comm_open() - a socket() wrapper, enforcing fd limitations and tagging the
86 file descriptor with a note
88 comm_accept() - an accept() wrapper, enforcing fd limitations and tagging
89 the file descriptor with a note
91 comm_connect_tcp() - attempt an async connect(). Handles DNS lookups if
92 required, and will call the given callback at completion or error
94 comm_settimeout() - set a callback to be called after a given time period.
95 This is good to implement things like PING checks and connect() timeouts.
99 * All socket creation should go through comm_open() / comm_accept().
100 * All socket closing should go through fd_close(). comm_close() isn't
102 * comm_connect_tcp() is your best friend. :-)
103 * *ALL* network sockets should be non-blocking. If your OS doesn't support
104 non-blocking sockets, you shouldn't be here.