[BACK]Return to timer.h CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / external / mpl / bind / dist / lib / isc / include / isc

Annotation of src/external/mpl/bind/dist/lib/isc/include/isc/timer.h, Revision 1.6

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

CVSweb <webmaster@jp.NetBSD.org>