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