doc/technical/network.txt

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