contrib/libbegemot/rpoll.man

   1 '\"
   2 '\" Copyright (c)1996-2006 by Hartmut Brandt
   3 '\"     All rights reserved.
   4 '\"
   5 '\" Author: harti@freebsd.org <Hartmut Brandt>
   6 '\"
   7 '\" Redistribution of this software and documentation and use in source and
   8 '\" binary forms, with or without modification, are permitted provided that
   9 '\" the following conditions are met:
  10 '\"
  11 '\" 1. Redistributions of source code or documentation must retain the above
  12 '\"   copyright notice, this list of conditions and the following disclaimer.
  13 '\" 2. Redistributions in binary form must reproduce the above copyright
  14 '\"   notice, this list of conditions and the following disclaimer in the
  15 '\"   documentation and/or other materials provided with the distribution.
  16 '\"
  17 '\" THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY THE AUTHOR
  18 '\" AND ITS CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  19 '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  20 '\" FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
  21 '\" THE AUTHOR OR ITS CONTRIBUTORS  BE LIABLE FOR ANY DIRECT, INDIRECT,
  22 '\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  23 '\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
  24 '\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  25 '\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  26 '\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  27 '\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 '\"
  29 '\" $Begemot: libbegemot/rpoll.man,v 1.4 2004/09/21 15:59:00 brandt Exp $
  30 '\"
  31 .TH rpoll 3 "8 Dec 2006" "BEGEMOT" "BEGEMOT Library"
  32 .SH NAME
  33 rpoll - callback functions for file descriptors and timers
  34 .SH SYNOPSIS
  35 .LP
  36 .B "# include <rpoll.h>"
  37 .LP
  38 .BR "typedef void (*poll_f)(int " "fd" ", int " "mask" ", void *" "arg" ");"
  39 .br
  40 .BR "typedef void (*timer_f)(int " "tid" ", void *" "arg" ");"
  41 .LP
  42 .BR "int poll_register(int " "fd" ", poll_f "
  43 .RB "func" ", void *" "arg" ", int " "mask" ");"
  44 .LP
  45 .BR "void poll_unregister(int " "handle" ");"
  46 .LP
  47 .BR "int poll_start_timer(u_int " "msecs" ", int " "repeat" ", timer_f " "func" ","
  48 .if n .ti +.5i
  49 .BR "void *" "arg" ");"
  50 .LP
  51 .BR "void poll_stop_timer(int " "handle" ");"
  52 .LP
  53 .BR "int poll_start_utimer(unsigned long long " "usecs" ", int " "repeat" ",
  54 .if n .ti +.5i
  55 .BR "timer_f " "func" ", void *" "arg" ");"
  56 .LP
  57 .BR "void poll_dispatch(int " "wait" ");"
  58 .SH DESCRIPTION
  59 Many programs need to read from several file descriptors at the same time.
  60 Typically in these programs one of
  61 .BR select (3c)
  62 or
  63 .BR poll (2)
  64 is used.
  65 These calls are however clumsy to use and the usage of one of these calls is
  66 probably not portable to other systems - not all systems support both calls.
  67 .LP
  68 The
  69 .BR rpoll (l)
  70 family of functions is designed to overcome these restrictions.
  71 They support the well known and understood technique of event driven
  72 programing and, in addition to
  73 .BR select (3c)
  74 and
  75 .BR poll (2)
  76 also support timers.
  77 .LP
  78 Each event on a file descriptor or each timer event is translated into a call to a user
  79 defined callback function. These functions need to be registered.
  80 A file descriptor is registered with
  81 .BR poll_register .
  82 .I fd
  83 is the file descriptor to watch,
  84 .I mask
  85 is an event mask.
  86 It may be any combination of
  87 .B POLL_IN
  88 to get informed when input on the file descriptor is possible,
  89 .B POLL_OUT
  90 to get informed when output is possible or
  91 .B POLL_EXCEPT
  92 to get informed when an exceptional condition occures.
  93 An example of an exceptional condition is the arrival of urgent data.
  94 (Note, that an end of file condition is signaled via POLL_IN).
  95 .I func
  96 is the user function to be called and
  97 .I arg
  98 is a user supplied argument for this function.
  99 The callback functions is called with the file descriptor, a mask
 100 describing the actual events (from the set supplied in the registration) and
 101 the user argument.
 102 .B poll_register
 103 returns a handle, which may be used later to de-register the file descriptor.
 104 A file descriptor may be registered more than once, if the function, the user arguments
 105 or both differ in the call to
 106 .BR poll_register .
 107 If
 108 .I func
 109 and
 110 .I arg
 111 are the same, then no new registration is done, instead the event mask of the registration
 112 is changed to reflect the new mask.
 113 .LP
 114 A registered file descriptor may be de-registered by calling
 115 .B poll_unregister
 116 with the handle returned by
 117 .BR poll_register .
 118 .LP
 119 A timer is created with
 120 .BR poll_start_timer
 121 or
 122 .BR poll_start_utimer .
 123 .I msecs
 124 is the number of milliseconds in
 125 .BR poll_start_timer
 126 while
 127 .I usecs
 128 is the number of microseconds in
 129 .BR poll_start_utimer ,
 130 after which the timer event will be generated.
 131 If the functions use the
 132 .BR poll (2)
 133 system call, then
 134 .I usecs
 135 is rounded to milliseconds and
 136 .BR poll_start_timer
 137 is called.
 138 .I repeat
 139 selects one-short behavior (if 0) or a repeatable timer (if not 0). A one-short timer
 140 will automatically unregistered after expiry.
 141 .I func
 142 is the user function which will be called with a timer id and the user supplied
 143 .IR arg .
 144 .B poll_start_timer
 145 and
 146 .B poll_start_utimer
 147 return a timer id, which may be used to cancel the timer with
 148 .BR poll_stop_timer .
 149 A one-short timer should be canceled only if it has not yet fired.
 150 .LP
 151 .B poll_dispatch
 152 must be called to actually dispatch events.
 153 .I wait
 154 is a flag, which should be 0, if only a poll should be done. In this case, the function returns,
 155 after polling the registered file descriptors and timers. If
 156 .I wait
 157 is not 0,
 158 .B poll_dispatch
 159 waits until an event occures. All events are dispatch (i.e. callback functions called) and
 160 .B poll_dispatch returns.
 161 .LP
 162 Typical use is:
 163 .LP
 164 .RS
 165 .nf
 166 .ft 3
 167 while(1)
 168         poll_dispatch(1);
 169 .ft 1
 170 .fi
 171 .RE
 172 .SH "SEE ALSO"
 173 .BR poll (2), select (3C)
 174 .SH "RETURN VALUES"
 175 .B poll_register ,
 176 .B poll_start_timer
 177 and
 178 .B poll_start_utimer
 179 return a handle which may be used to unregister the file descriptor or
 180 cancel the timer.
 181 .LP
 182 Both functions and
 183 .B poll_dispatch
 184 call
 185 .BR xrealloc (l)
 186 and can end in
 187 .BR panic (l).
 188 .SH "ERRORS"
 189 System call or memory allocation errors are fatal and are handle by calling
 190 .BR panic (l).
 191 The one exception is a return of EINTR from
 192 .BR select (3c)
 193 or
 194 .BR poll (2)
 195 in
 196 .BR poll_dispatch .
 197 In this case
 198 .B poll_dispatch
 199 simply returns.
 200 .SH "BUGS"
 201 Obscure sequences of
 202 .B poll_start_timer
 203 and
 204 .B poll_stop_timer
 205 in callback functions may probably break the code.
 206 .LP
 207 The semantics of
 208 .B POLL_EXCEPT
 209 are not clear.
 210 .SH AUTHORS
 211 Hartmut Brandt, harti@freebsd.org