doc/technical/network.txt

   1 Overview of the network subsystem
   2 Adrian Chadd <adrian@creative.net.au>
   3
   4 $Id: network.txt 6 2005-09-10 01:02:21Z nenolod $
   5
   6
   7 This document is an overview of the new and hopefully improved network
   8 subsystem.
   9
  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.
  12
  13
  14
  15 Filedescriptor IO
  16 -----------------
  17
  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
  21 from the IO loop.
  22
  23 The comm_setselect() usage is:
  24
  25 void
  26 comm_setselect(int fd, fdlist_t list, int type, PF *callback, void *cbdata,
  27     int timeout)
  28
  29 where:
  30   fd            filedescriptor
  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".
  38
  39
  40 A typical use is:
  41
  42 ..
  43
  44 /* Register interest in the FD for a read event */
  45 comm_setselect(fd, FDLIST_SERVICE, COMM_SELECT_READ, read_callback, read_data,
  46     0);
  47
  48 ..
  49
  50 (FD becomes ready for read in the IO loop)
  51
  52 void
  53 read_callback(int fd, void *data)
  54 {
  55     /* called when the FD becomes ready for read */
  56     retval = read(fd, buf, len);
  57
  58     ..
  59     /* Ok, we need to read some more when its ready */
  60     comm_setselect(fd, FDLIST_SERVICE, COMM_SELECT_READ, read_callback, data,
  61         0);
  62 }
  63
  64
  65
  66
  67 Socket timeouts
  68 ---------------
  69
  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.
  72
  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.
  79
  80
  81
  82
  83 Functions
  84 ---------
  85
  86 comm_open() - a socket() wrapper, enforcing fd limitations and tagging the
  87   file descriptor with a note
  88
  89 comm_accept() - an accept() wrapper, enforcing fd limitations and tagging
  90   the file descriptor with a note
  91
  92 comm_connect_tcp() - attempt an async connect(). Handles DNS lookups if
  93   required, and will call the given callback at completion or error
  94
  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.
  97
  98 Notes:
  99
 100 * All socket creation should go through comm_open() / comm_accept().
 101 * All socket closing should go through fd_close(). comm_close() isn't
 102   implemented yet.
 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.