doc/design/dispatch

   1 Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   2 Copyright (C) 2000, 2001  Internet Software Consortium.
   3 See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
   4
   5 $Id: dispatch,v 1.6 2004/03/05 05:04:46 marka Exp $
   6
   7 UDP receive:
   8
   9 /*
  10  * General flow:
  11  *
  12  * If I/O result == CANCELED, free the buffer and notify everyone as
  13  * the various queues drain.
  14  *
  15  * If I/O is error (not canceled and not success) log it, free the buffer,
  16  * and restart.
  17  *
  18  * If query:
  19  *      if no listeners: free the buffer, restart.
  20  *      if listener: allocate event, fill in details.
  21  *              If cannot allocate, free buffer, restart.
  22  *      if rq event queue is not empty, queue.  else, send.
  23  *      restart.
  24  *
  25  * If response:
  26  *      Allocate event, fill in details.
  27  *              If cannot allocate, free buffer, restart.
  28  *      find target.  If not found, free buffer, restart.
  29  *      if event queue is not empty, queue.  else, send.
  30  *      restart.
  31  */
  32
  33
  34 UDP restart:
  35
  36 /*
  37  * If too many recv()'s are already running, just return.
  38  *
  39  * If noone is attached to us, just return.
  40  *
  41  * Allocate a new buffer to receive into.
  42  * If no more buffers:
  43  *      If there are buffers handed out: wait for one to come back.
  44  *      If there are no buffers handed out:
  45  *              If there are responses attached to us, just return.
  46  *              If there are queries only, send one an error event.
  47  *
  48  *
  49  * start recv() on socket.  If this fails:
  50  *      Free buffer.
  51  *      Set dispatch state to "shutting down" and why to "socket error"
  52  *      Start failsafe shutdown.
  53  */
  54
  55
  56 Adding a response:
  57
  58 /*
  59  * If shutting down, return error.
  60  *
  61  * Allocate an unique messageid and return it.  If none can be allocated,
  62  * return that.
  63  *
  64  * Allocate a new structure and fill it in.  If no memory, return that.
  65  *
  66  * Insert into the correct linked list.
  67  *
  68  * If the receiver is not running, try to start it.
  69  */
  70
  71 Adding a request:
  72
  73 /*
  74  * If shutting down, return error.
  75  *
  76  * Allocate new structure and fill it in.  If no memory, return that.
  77  *
  78  * Insert it into the linked list.
  79  *
  80  * If the incoming query packet queue is not empty, pull an item off and
  81  * send that event to this task.
  82  *
  83  * If the receiver is not running, try to start it.
  84  */
  85
  86 Detaching a response:
  87
  88 /*
  89  * decrement dispatch reference count by one.  If zero, remember to kill it
  90  * later.
  91  *
  92  * unlink the response from the hashed list.
  93  *
  94  * Free any buffers and events attached to the response structure.
  95  *
  96  * Free the response structure.
  97  *
  98  * If an event is also being returned, jump to "internal event free" below.
  99  *
 100  * If the ref count became zero above, destroy this dispatch fully, and return.
 101  *
 102  * If the receiver is not running, try to start it.
 103  */
 104
 105 Detaching a request:
 106
 107 /*
 108  * decrement dispatch ref count by one.  If zero, remember to kill it later.
 109  *
 110  * unlink from the request list.
 111  *
 112  * Free the response structure.
 113  *
 114  * If an event is also being returned, jump to "internal event free" below.
 115  *
 116  * If the ref count became zero above, destroy the dispatch fully, and return.
 117  *
 118  * If the receiver is not running, try to start it.
 119  */
 120
 121 Internal event free (from library space):
 122
 123 /*
 124  * If it is the failsafe event, send it to the next response/request on the
 125  * dispatcher, and return.
 126  *
 127  * Free buffer.
 128  *
 129  * Free event.
 130  */
 131
 132 Returning an event (from application space):
 133
 134 /*
 135  * If it is the failsafe event, die.
 136  *
 137  * Free associated buffer.
 138  *
 139  * Free event.
 140  *
 141  * If response:  do next response on this response's queue, if any.
 142  * If request:  do next request on this dispatcher's queue, if any.
 143  *
 144  * If the receiver is not running, try to start it.
 145  */
 146