contrib/putty/CONTRIB/CYGTERMD/SEL.H

   1 /*\r
   2  * sel.h: subsystem to manage the grubby details of a select loop,\r
   3  * buffering data to write, and performing the actual writes and\r
   4  * reads.\r
   5  */\r
   6 \r
   7 #ifndef FIXME_SEL_H\r
   8 #define FIXME_SEL_H\r
   9 \r
  10 typedef struct sel sel;\r
  11 typedef struct sel_wfd sel_wfd;\r
  12 typedef struct sel_rfd sel_rfd;\r
  13 \r
  14 /*\r
  15  * Callback called when some data is written to a wfd. "bufsize"\r
  16  * is the remaining quantity of data buffered in that wfd.\r
  17  */\r
  18 typedef void (*sel_written_fn_t)(sel_wfd *wfd, size_t bufsize);\r
  19 \r
  20 /*\r
  21  * Callback called when an error occurs on a wfd, preventing\r
  22  * further writing to it. "error" is the errno value.\r
  23  */\r
  24 typedef void (*sel_writeerr_fn_t)(sel_wfd *wfd, int error);\r
  25 \r
  26 /*\r
  27  * Callback called when some data is read from an rfd. On EOF,\r
  28  * this will be called with len==0.\r
  29  */\r
  30 typedef void (*sel_readdata_fn_t)(sel_rfd *rfd, void *data, size_t len);\r
  31 \r
  32 /*\r
  33  * Callback called when an error occurs on an rfd, preventing\r
  34  * further reading from it. "error" is the errno value.\r
  35  */\r
  36 typedef void (*sel_readerr_fn_t)(sel_rfd *rfd, int error);\r
  37 \r
  38 /*\r
  39  * Create a sel structure, which will oversee a select loop.\r
  40  * \r
  41  * "ctx" is user-supplied data stored in the sel structure; it can\r
  42  * be read and written with sel_get_ctx() and sel_set_ctx().\r
  43  */\r
  44 sel *sel_new(void *ctx);\r
  45 \r
  46 /*\r
  47  * Add a new fd for writing. Returns a sel_wfd which identifies\r
  48  * that fd in the sel structure, e.g. for putting data into its\r
  49  * output buffer.\r
  50  * \r
  51  * "ctx" is user-supplied data stored in the sel structure; it can\r
  52  * be read and written with sel_wfd_get_ctx() and sel_wfd_set_ctx().\r
  53  * \r
  54  * "written" and "writeerr" are called from the event loop when\r
  55  * things happen.\r
  56  *\r
  57  * The fd passed in can be -1, in which case it will be assumed to\r
  58  * be unwritable at all times. An actual fd can be passed in later\r
  59  * using sel_wfd_setfd.\r
  60  */\r
  61 sel_wfd *sel_wfd_add(sel *sel, int fd,\r
  62                      sel_written_fn_t written, sel_writeerr_fn_t writeerr,\r
  63                      void *ctx);\r
  64 \r
  65 /*\r
  66  * Add a new fd for reading. Returns a sel_rfd which identifies\r
  67  * that fd in the sel structure.\r
  68  * \r
  69  * "ctx" is user-supplied data stored in the sel structure; it can\r
  70  * be read and written with sel_rfd_get_ctx() and sel_rfd_set_ctx().\r
  71  * \r
  72  * "readdata" and "readerr" are called from the event loop when\r
  73  * things happen. "ctx" is passed to both of them.\r
  74  */\r
  75 sel_rfd *sel_rfd_add(sel *sel, int fd,\r
  76                      sel_readdata_fn_t readdata, sel_readerr_fn_t readerr,\r
  77                      void *ctx);\r
  78 \r
  79 /*\r
  80  * Write data into the output buffer of a wfd. Returns the new\r
  81  * size of the output buffer. (You can call it with len==0 if you\r
  82  * just want to know the buffer size; in that situation data==NULL\r
  83  * is also safe.)\r
  84  */\r
  85 size_t sel_write(sel_wfd *wfd, const void *data, size_t len);\r
  86 \r
  87 /*\r
  88  * Freeze and unfreeze an rfd. When frozen, sel will temporarily\r
  89  * not attempt to read from it, but all its state is retained so\r
  90  * it can be conveniently unfrozen later. (You might use this\r
  91  * facility, for instance, if what you were doing with the\r
  92  * incoming data could only accept it at a certain rate: freeze\r
  93  * the rfd when you've got lots of backlog, and unfreeze it again\r
  94  * when things get calmer.)\r
  95  */\r
  96 void sel_rfd_freeze(sel_rfd *rfd);\r
  97 void sel_rfd_unfreeze(sel_rfd *rfd);\r
  98 \r
  99 /*\r
 100  * Delete a wfd structure from its containing sel. Returns the\r
 101  * underlying fd, which the client may now consider itself to own\r
 102  * once more.\r
 103  */\r
 104 int sel_wfd_delete(sel_wfd *wfd);\r
 105 \r
 106 /*\r
 107  * Delete an rfd structure from its containing sel. Returns the\r
 108  * underlying fd, which the client may now consider itself to own\r
 109  * once more.\r
 110  */\r
 111 int sel_rfd_delete(sel_rfd *rfd);\r
 112 \r
 113 /*\r
 114  * NOT IMPLEMENTED YET: useful functions here might be ones which\r
 115  * enumerated all the wfds/rfds in a sel structure in some\r
 116  * fashion, so you could go through them and remove them all while\r
 117  * doing sensible things to them. Or, at the very least, just\r
 118  * return an arbitrary one of the wfds/rfds.\r
 119  */\r
 120 \r
 121 /*\r
 122  * Free a sel structure and all its remaining wfds and rfds.\r
 123  */\r
 124 void sel_free(sel *sel);\r
 125 \r
 126 /*\r
 127  * Read and write the ctx parameters in sel, sel_wfd and sel_rfd.\r
 128  */\r
 129 void *sel_get_ctx(sel *sel);\r
 130 void sel_set_ctx(sel *sel, void *ctx);\r
 131 void *sel_wfd_get_ctx(sel_wfd *wfd);\r
 132 void sel_wfd_set_ctx(sel_wfd *wfd, void *ctx);\r
 133 void *sel_rfd_get_ctx(sel_rfd *rfd);\r
 134 void sel_rfd_set_ctx(sel_rfd *rfd, void *ctx);\r
 135 \r
 136 /*\r
 137  * Run one iteration of the sel event loop, calling callbacks as\r
 138  * necessary. Returns zero on success; in the event of a fatal\r
 139  * error, returns the errno value.\r
 140  * \r
 141  * "timeout" is a value in microseconds to limit the length of the\r
 142  * select call. Less than zero means to wait indefinitely.\r
 143  */\r
 144 int sel_iterate(sel *sel, long timeout);\r
 145 \r
 146 /*\r
 147  * Change the underlying fd in a wfd. If set to -1, no write\r
 148  * attempts will take place and the wfd's buffer will simply store\r
 149  * everything passed to sel_write(). If later set to something\r
 150  * other than -1, all that buffered data will become eligible for\r
 151  * real writing.\r
 152  */\r
 153 void sel_wfd_setfd(sel_wfd *wfd, int fd);\r
 154 \r
 155 /*\r
 156  * Change the underlying fd in a rfd. If set to -1, no read\r
 157  * attempts will take place.\r
 158  */\r
 159 void sel_rfd_setfd(sel_rfd *rfd, int fd);\r
 160 \r
 161 #endif /* FIXME_SEL_H */\r