contrib/bind-9.3/lib/isc/include/isc/timer.h

   1 /*
   2  * Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1998-2002  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id: timer.h,v 1.28.12.6 2005/10/27 00:27:30 marka Exp $ */
  19
  20 #ifndef ISC_TIMER_H
  21 #define ISC_TIMER_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*
  28  * Timers
  29  *
  30  * Provides timers which are event sources in the task system.
  31  *
  32  * Three types of timers are supported:
  33  *
  34  *      'ticker' timers generate a periodic tick event.
  35  *
  36  *      'once' timers generate an idle timeout event if they are idle for too
  37  *      long, and generate a life timeout event if their lifetime expires.
  38  *      They are used to implement both (possibly expiring) idle timers and
  39  *      'one-shot' timers.
  40  *
  41  *      'limited' timers generate a periodic tick event until they reach
  42  *      their lifetime when they generate a life timeout event.
  43  *
  44  *      'inactive' timers generate no events.
  45  *
  46  * Timers can change type.  It is typical to create a timer as
  47  * an 'inactive' timer and then change it into a 'ticker' or
  48  * 'once' timer.
  49  *
  50  * MP:
  51  *      The module ensures appropriate synchronization of data structures it
  52  *      creates and manipulates.
  53  *
  54  *      Clients of this module must not be holding a timer's task's lock when
  55  *      making a call that affects that timer.  Failure to follow this rule
  56  *      can result in deadlock.
  57  *
  58  *      The caller must ensure that isc_timermgr_destroy() is called only
  59  *      once for a given manager.
  60  *
  61  * Reliability:
  62  *      No anticipated impact.
  63  *
  64  * Resources:
  65  *      <TBS>
  66  *
  67  * Security:
  68  *      No anticipated impact.
  69  *
  70  * Standards:
  71  *      None.
  72  */
  73
  74
  75 /***
  76  *** Imports
  77  ***/
  78
  79 #include <isc/types.h>
  80 #include <isc/event.h>
  81 #include <isc/eventclass.h>
  82 #include <isc/lang.h>
  83
  84 ISC_LANG_BEGINDECLS
  85
  86 /***
  87  *** Types
  88  ***/
  89
  90 typedef enum {
  91         isc_timertype_ticker = 0,
  92         isc_timertype_once = 1,
  93         isc_timertype_limited = 2,
  94         isc_timertype_inactive = 3
  95 } isc_timertype_t;
  96
  97 typedef struct isc_timerevent {
  98         struct isc_event        common;
  99 } isc_timerevent_t;
 100
 101 #define ISC_TIMEREVENT_FIRSTEVENT       (ISC_EVENTCLASS_TIMER + 0)
 102 #define ISC_TIMEREVENT_TICK             (ISC_EVENTCLASS_TIMER + 1)
 103 #define ISC_TIMEREVENT_IDLE             (ISC_EVENTCLASS_TIMER + 2)
 104 #define ISC_TIMEREVENT_LIFE             (ISC_EVENTCLASS_TIMER + 3)
 105 #define ISC_TIMEREVENT_LASTEVENT        (ISC_EVENTCLASS_TIMER + 65535)
 106
 107 /***
 108  *** Timer and Timer Manager Functions
 109  ***
 110  *** Note: all Ensures conditions apply only if the result is success for
 111  *** those functions which return an isc_result_t.
 112  ***/
 113
 114 isc_result_t
 115 isc_timer_create(isc_timermgr_t *manager,
 116                  isc_timertype_t type,
 117                  isc_time_t *expires,
 118                  isc_interval_t *interval,
 119                  isc_task_t *task,
 120                  isc_taskaction_t action,
 121                  const void *arg,
 122                  isc_timer_t **timerp);
 123 /*
 124  * Create a new 'type' timer managed by 'manager'.  The timers parameters
 125  * are specified by 'expires' and 'interval'.  Events will be posted to
 126  * 'task' and when dispatched 'action' will be called with 'arg' as the
 127  * arg value.  The new timer is returned in 'timerp'.
 128  *
 129  * Notes:
 130  *
 131  *      For ticker timers, the timer will generate a 'tick' event every
 132  *      'interval' seconds.  The value of 'expires' is ignored.
 133  *
 134  *      For once timers, 'expires' specifies the time when a life timeout
 135  *      event should be generated.  If 'expires' is 0 (the epoch), then no life
 136  *      timeout will be generated.  'interval' specifies how long the timer
 137  *      can be idle before it generates an idle timeout.  If 0, then no
 138  *      idle timeout will be generated.
 139  *
 140  *      If 'expires' is NULL, the epoch will be used.
 141  *
 142  *      If 'interval' is NULL, the zero interval will be used.
 143  *
 144  * Requires:
 145  *
 146  *      'manager' is a valid manager
 147  *
 148  *      'task' is a valid task
 149  *
 150  *      'action' is a valid action
 151  *
 152  *      'expires' points to a valid time, or is NULL.
 153  *
 154  *      'interval' points to a valid interval, or is NULL.
 155  *
 156  *      type == isc_timertype_inactive ||
 157  *      ('expires' and 'interval' are not both 0)
 158  *
 159  *      'timerp' is a valid pointer, and *timerp == NULL
 160  *
 161  * Ensures:
 162  *
 163  *      '*timerp' is attached to the newly created timer
 164  *
 165  *      The timer is attached to the task
 166  *
 167  *      An idle timeout will not be generated until at least Now + the
 168  *      timer's interval if 'timer' is a once timer with a non-zero
 169  *      interval.
 170  *
 171  * Returns:
 172  *
 173  *      Success
 174  *      No memory
 175  *      Unexpected error
 176  */
 177
 178 isc_result_t
 179 isc_timer_reset(isc_timer_t *timer,
 180                 isc_timertype_t type,
 181                 isc_time_t *expires,
 182                 isc_interval_t *interval,
 183                 isc_boolean_t purge);
 184 /*
 185  * Change the timer's type, expires, and interval values to the given
 186  * values.  If 'purge' is TRUE, any pending events from this timer
 187  * are purged from its task's event queue.
 188  *
 189  * Notes:
 190  *
 191  *      If 'expires' is NULL, the epoch will be used.
 192  *
 193  *      If 'interval' is NULL, the zero interval will be used.
 194  *
 195  * Requires:
 196  *
 197  *      'timer' is a valid timer
 198  *
 199  *      The same requirements that isc_timer_create() imposes on 'type',
 200  *      'expires' and 'interval' apply.
 201  *
 202  * Ensures:
 203  *
 204  *      An idle timeout will not be generated until at least Now + the
 205  *      timer's interval if 'timer' is a once timer with a non-zero
 206  *      interval.
 207  *
 208  * Returns:
 209  *
 210  *      Success
 211  *      No memory
 212  *      Unexpected error
 213  */
 214
 215 isc_result_t
 216 isc_timer_touch(isc_timer_t *timer);
 217 /*
 218  * Set the last-touched time of 'timer' to the current time.
 219  *
 220  * Requires:
 221  *
 222  *      'timer' is a valid once timer.
 223  *
 224  * Ensures:
 225  *
 226  *      An idle timeout will not be generated until at least Now + the
 227  *      timer's interval if 'timer' is a once timer with a non-zero
 228  *      interval.
 229  *
 230  * Returns:
 231  *
 232  *      Success
 233  *      Unexpected error
 234  */
 235
 236 void
 237 isc_timer_attach(isc_timer_t *timer, isc_timer_t **timerp);
 238 /*
 239  * Attach *timerp to timer.
 240  *
 241  * Requires:
 242  *
 243  *      'timer' is a valid timer.
 244  *
 245  *      'timerp' points to a NULL timer.
 246  *
 247  * Ensures:
 248  *
 249  *      *timerp is attached to timer.
 250  */
 251
 252 void
 253 isc_timer_detach(isc_timer_t **timerp);
 254 /*
 255  * Detach *timerp from its timer.
 256  *
 257  * Requires:
 258  *
 259  *      'timerp' points to a valid timer.
 260  *
 261  * Ensures:
 262  *
 263  *      *timerp is NULL.
 264  *
 265  *      If '*timerp' is the last reference to the timer,
 266  *      then:
 267  *
 268  *              The timer will be shutdown
 269  *
 270  *              The timer will detach from its task
 271  *
 272  *              All resources used by the timer have been freed
 273  *
 274  *              Any events already posted by the timer will be purged.
 275  *              Therefore, if isc_timer_detach() is called in the context
 276  *              of the timer's task, it is guaranteed that no more
 277  *              timer event callbacks will run after the call.
 278  */
 279
 280 isc_timertype_t
 281 isc_timer_gettype(isc_timer_t *timer);
 282 /*%<
 283  * Return the timer type.
 284  *
 285  * Requires:
 286  *
 287  *\li   'timer' to be a valid timer.
 288  */
 289
 290 isc_result_t
 291 isc_timermgr_create(isc_mem_t *mctx, isc_timermgr_t **managerp);
 292 /*
 293  * Create a timer manager.
 294  *
 295  * Notes:
 296  *
 297  *      All memory will be allocated in memory context 'mctx'.
 298  *
 299  * Requires:
 300  *
 301  *      'mctx' is a valid memory context.
 302  *
 303  *      'managerp' points to a NULL isc_timermgr_t.
 304  *
 305  * Ensures:
 306  *
 307  *      '*managerp' is a valid isc_timermgr_t.
 308  *
 309  * Returns:
 310  *
 311  *      Success
 312  *      No memory
 313  *      Unexpected error
 314  */
 315
 316 void
 317 isc_timermgr_destroy(isc_timermgr_t **managerp);
 318 /*
 319  * Destroy a timer manager.
 320  *
 321  * Notes:
 322  *
 323  *      This routine blocks until there are no timers left in the manager,
 324  *      so if the caller holds any timer references using the manager, it
 325  *      must detach them before calling isc_timermgr_destroy() or it will
 326  *      block forever.
 327  *
 328  * Requires:
 329  *
 330  *      '*managerp' is a valid isc_timermgr_t.
 331  *
 332  * Ensures:
 333  *
 334  *      *managerp == NULL
 335  *
 336  *      All resources used by the manager have been freed.
 337  */
 338
 339 void isc_timermgr_poke(isc_timermgr_t *m);
 340
 341 ISC_LANG_ENDDECLS
 342
 343 #endif /* ISC_TIMER_H */