/*

[0] Fix | Delete

* Copyright (C) Internet Systems Consortium, Inc. ("ISC")

[1] Fix | Delete

*

[2] Fix | Delete

* This Source Code Form is subject to the terms of the Mozilla Public

[3] Fix | Delete

* License, v. 2.0. If a copy of the MPL was not distributed with this

[4] Fix | Delete

* file, you can obtain one at https://mozilla.org/MPL/2.0/.

[5] Fix | Delete

*

[6] Fix | Delete

* See the COPYRIGHT file distributed with this work for additional

[7] Fix | Delete

* information regarding copyright ownership.

[8] Fix | Delete

*/

[9] Fix | Delete

[10] Fix | Delete

[11] Fix | Delete

#ifndef ISC_TIMER_H

[12] Fix | Delete

#define ISC_TIMER_H 1

[13] Fix | Delete

[14] Fix | Delete

/*****

[15] Fix | Delete

***** Module Info

[16] Fix | Delete

*****/

[17] Fix | Delete

[18] Fix | Delete

/*! \file isc/timer.h

[19] Fix | Delete

* \brief Provides timers which are event sources in the task system.

[20] Fix | Delete

*

[21] Fix | Delete

* Three types of timers are supported:

[22] Fix | Delete

*

[23] Fix | Delete

*\li 'ticker' timers generate a periodic tick event.

[24] Fix | Delete

*

[25] Fix | Delete

*\li 'once' timers generate an idle timeout event if they are idle for too

[26] Fix | Delete

* long, and generate a life timeout event if their lifetime expires.

[27] Fix | Delete

* They are used to implement both (possibly expiring) idle timers and

[28] Fix | Delete

* 'one-shot' timers.

[29] Fix | Delete

*

[30] Fix | Delete

*\li 'limited' timers generate a periodic tick event until they reach

[31] Fix | Delete

* their lifetime when they generate a life timeout event.

[32] Fix | Delete

*

[33] Fix | Delete

*\li 'inactive' timers generate no events.

[34] Fix | Delete

*

[35] Fix | Delete

* Timers can change type. It is typical to create a timer as

[36] Fix | Delete

* an 'inactive' timer and then change it into a 'ticker' or

[37] Fix | Delete

* 'once' timer.

[38] Fix | Delete

*

[39] Fix | Delete

*\li MP:

[40] Fix | Delete

* The module ensures appropriate synchronization of data structures it

[41] Fix | Delete

* creates and manipulates.

[42] Fix | Delete

* Clients of this module must not be holding a timer's task's lock when

[43] Fix | Delete

* making a call that affects that timer. Failure to follow this rule

[44] Fix | Delete

* can result in deadlock.

[45] Fix | Delete

* The caller must ensure that isc_timermgr_destroy() is called only

[46] Fix | Delete

* once for a given manager.

[47] Fix | Delete

*

[48] Fix | Delete

* \li Reliability:

[49] Fix | Delete

* No anticipated impact.

[50] Fix | Delete

*

[51] Fix | Delete

* \li Resources:

[52] Fix | Delete

* TBS

[53] Fix | Delete

*

[54] Fix | Delete

* \li Security:

[55] Fix | Delete

* No anticipated impact.

[56] Fix | Delete

*

[57] Fix | Delete

* \li Standards:

[58] Fix | Delete

* None.

[59] Fix | Delete

*/

[60] Fix | Delete

[61] Fix | Delete

[62] Fix | Delete

/***

[63] Fix | Delete

*** Imports

[64] Fix | Delete

***/

[65] Fix | Delete

[66] Fix | Delete

#include <stdbool.h>

[67] Fix | Delete

[68] Fix | Delete

#include <isc/types.h>

[69] Fix | Delete

#include <isc/event.h>

[70] Fix | Delete

#include <isc/eventclass.h>

[71] Fix | Delete

#include <isc/lang.h>

[72] Fix | Delete

#include <isc/time.h>

[73] Fix | Delete

[74] Fix | Delete

ISC_LANG_BEGINDECLS

[75] Fix | Delete

[76] Fix | Delete

/***

[77] Fix | Delete

*** Types

[78] Fix | Delete

***/

[79] Fix | Delete

[80] Fix | Delete

/*% Timer Type */

[81] Fix | Delete

typedef enum {

[82] Fix | Delete

isc_timertype_undefined = -1, /*%< Undefined */

[83] Fix | Delete

isc_timertype_ticker = 0, /*%< Ticker */

[84] Fix | Delete

isc_timertype_once = 1, /*%< Once */

[85] Fix | Delete

isc_timertype_limited = 2, /*%< Limited */

[86] Fix | Delete

isc_timertype_inactive = 3 /*%< Inactive */

[87] Fix | Delete

} isc_timertype_t;

[88] Fix | Delete

[89] Fix | Delete

typedef struct isc_timerevent {

[90] Fix | Delete

struct isc_event common;

[91] Fix | Delete

isc_time_t due;

[92] Fix | Delete

} isc_timerevent_t;

[93] Fix | Delete

[94] Fix | Delete

#define ISC_TIMEREVENT_FIRSTEVENT (ISC_EVENTCLASS_TIMER + 0)

[95] Fix | Delete

#define ISC_TIMEREVENT_TICK (ISC_EVENTCLASS_TIMER + 1)

[96] Fix | Delete

#define ISC_TIMEREVENT_IDLE (ISC_EVENTCLASS_TIMER + 2)

[97] Fix | Delete

#define ISC_TIMEREVENT_LIFE (ISC_EVENTCLASS_TIMER + 3)

[98] Fix | Delete

#define ISC_TIMEREVENT_LASTEVENT (ISC_EVENTCLASS_TIMER + 65535)

[99] Fix | Delete

[100] Fix | Delete

/*% Timer and timer manager methods */

[101] Fix | Delete

typedef struct {

[102] Fix | Delete

void (*destroy)(isc_timermgr_t **managerp);

[103] Fix | Delete

isc_result_t (*timercreate)(isc_timermgr_t *manager,

[104] Fix | Delete

isc_timertype_t type,

[105] Fix | Delete

const isc_time_t *expires,

[106] Fix | Delete

const isc_interval_t *interval,

[107] Fix | Delete

isc_task_t *task,

[108] Fix | Delete

isc_taskaction_t action,

[109] Fix | Delete

void *arg,

[110] Fix | Delete

isc_timer_t **timerp);

[111] Fix | Delete

} isc_timermgrmethods_t;

[112] Fix | Delete

[113] Fix | Delete

typedef struct {

[114] Fix | Delete

void (*attach)(isc_timer_t *timer, isc_timer_t **timerp);

[115] Fix | Delete

void (*detach)(isc_timer_t **timerp);

[116] Fix | Delete

isc_result_t (*reset)(isc_timer_t *timer, isc_timertype_t type,

[117] Fix | Delete

const isc_time_t *expires,

[118] Fix | Delete

const isc_interval_t *interval,

[119] Fix | Delete

bool purge);

[120] Fix | Delete

isc_result_t (*touch)(isc_timer_t *timer);

[121] Fix | Delete

} isc_timermethods_t;

[122] Fix | Delete

[123] Fix | Delete

/*%

[124] Fix | Delete

* This structure is actually just the common prefix of a timer manager

[125] Fix | Delete

* object implementation's version of an isc_timermgr_t.

[126] Fix | Delete

* \brief

[127] Fix | Delete

* Direct use of this structure by clients is forbidden. timer implementations

[128] Fix | Delete

* may change the structure. 'magic' must be ISCAPI_TIMERMGR_MAGIC for any

[129] Fix | Delete

* of the isc_timer_ routines to work. timer implementations must maintain

[130] Fix | Delete

* all timer invariants.

[131] Fix | Delete

*/

[132] Fix | Delete

struct isc_timermgr {

[133] Fix | Delete

unsigned int impmagic;

[134] Fix | Delete

unsigned int magic;

[135] Fix | Delete

isc_timermgrmethods_t *methods;

[136] Fix | Delete

};

[137] Fix | Delete

[138] Fix | Delete

#define ISCAPI_TIMERMGR_MAGIC ISC_MAGIC('A','t','m','g')

[139] Fix | Delete

#define ISCAPI_TIMERMGR_VALID(m) ((m) != NULL && \

[140] Fix | Delete

(m)->magic == ISCAPI_TIMERMGR_MAGIC)

[141] Fix | Delete

[142] Fix | Delete

/*%

[143] Fix | Delete

* This is the common prefix of a timer object. The same note as

[144] Fix | Delete

* that for the timermgr structure applies.

[145] Fix | Delete

*/

[146] Fix | Delete

struct isc_timer {

[147] Fix | Delete

unsigned int impmagic;

[148] Fix | Delete

unsigned int magic;

[149] Fix | Delete

isc_timermethods_t *methods;

[150] Fix | Delete

};

[151] Fix | Delete

[152] Fix | Delete

#define ISCAPI_TIMER_MAGIC ISC_MAGIC('A','t','m','r')

[153] Fix | Delete

#define ISCAPI_TIMER_VALID(s) ((s) != NULL && \

[154] Fix | Delete

(s)->magic == ISCAPI_TIMER_MAGIC)

[155] Fix | Delete

[156] Fix | Delete

/***

[157] Fix | Delete

*** Timer and Timer Manager Functions

[158] Fix | Delete

***

[159] Fix | Delete

*** Note: all Ensures conditions apply only if the result is success for

[160] Fix | Delete

*** those functions which return an isc_result_t.

[161] Fix | Delete

***/

[162] Fix | Delete

[163] Fix | Delete

isc_result_t

[164] Fix | Delete

isc_timer_create(isc_timermgr_t *manager,

[165] Fix | Delete

isc_timertype_t type,

[166] Fix | Delete

const isc_time_t *expires,

[167] Fix | Delete

const isc_interval_t *interval,

[168] Fix | Delete

isc_task_t *task,

[169] Fix | Delete

isc_taskaction_t action,

[170] Fix | Delete

void *arg,

[171] Fix | Delete

isc_timer_t **timerp);

[172] Fix | Delete

/*%<

[173] Fix | Delete

* Create a new 'type' timer managed by 'manager'. The timers parameters

[174] Fix | Delete

* are specified by 'expires' and 'interval'. Events will be posted to

[175] Fix | Delete

* 'task' and when dispatched 'action' will be called with 'arg' as the

[176] Fix | Delete

* arg value. The new timer is returned in 'timerp'.

[177] Fix | Delete

*

[178] Fix | Delete

* Notes:

[179] Fix | Delete

*

[180] Fix | Delete

*\li For ticker timers, the timer will generate a 'tick' event every

[181] Fix | Delete

* 'interval' seconds. The value of 'expires' is ignored.

[182] Fix | Delete

*

[183] Fix | Delete

*\li For once timers, 'expires' specifies the time when a life timeout

[184] Fix | Delete

* event should be generated. If 'expires' is 0 (the epoch), then no life

[185] Fix | Delete

* timeout will be generated. 'interval' specifies how long the timer

[186] Fix | Delete

* can be idle before it generates an idle timeout. If 0, then no

[187] Fix | Delete

* idle timeout will be generated.

[188] Fix | Delete

*

[189] Fix | Delete

*\li If 'expires' is NULL, the epoch will be used.

[190] Fix | Delete

*

[191] Fix | Delete

* If 'interval' is NULL, the zero interval will be used.

[192] Fix | Delete

*

[193] Fix | Delete

* Requires:

[194] Fix | Delete

*

[195] Fix | Delete

*\li 'manager' is a valid manager

[196] Fix | Delete

*

[197] Fix | Delete

*\li 'task' is a valid task

[198] Fix | Delete

*

[199] Fix | Delete

*\li 'action' is a valid action

[200] Fix | Delete

*

[201] Fix | Delete

*\li 'expires' points to a valid time, or is NULL.

[202] Fix | Delete

*

[203] Fix | Delete

*\li 'interval' points to a valid interval, or is NULL.

[204] Fix | Delete

*

[205] Fix | Delete

*\li type == isc_timertype_inactive ||

[206] Fix | Delete

* ('expires' and 'interval' are not both 0)

[207] Fix | Delete

*

[208] Fix | Delete

*\li 'timerp' is a valid pointer, and *timerp == NULL

[209] Fix | Delete

*

[210] Fix | Delete

* Ensures:

[211] Fix | Delete

*

[212] Fix | Delete

*\li '*timerp' is attached to the newly created timer

[213] Fix | Delete

*

[214] Fix | Delete

*\li The timer is attached to the task

[215] Fix | Delete

*

[216] Fix | Delete

*\li An idle timeout will not be generated until at least Now + the

[217] Fix | Delete

* timer's interval if 'timer' is a once timer with a non-zero

[218] Fix | Delete

* interval.

[219] Fix | Delete

*

[220] Fix | Delete

* Returns:

[221] Fix | Delete

*

[222] Fix | Delete

*\li Success

[223] Fix | Delete

*\li No memory

[224] Fix | Delete

*\li Unexpected error

[225] Fix | Delete

*/

[226] Fix | Delete

[227] Fix | Delete

isc_result_t

[228] Fix | Delete

isc_timer_reset(isc_timer_t *timer,

[229] Fix | Delete

isc_timertype_t type,

[230] Fix | Delete

const isc_time_t *expires,

[231] Fix | Delete

const isc_interval_t *interval,

[232] Fix | Delete

bool purge);

[233] Fix | Delete

/*%<

[234] Fix | Delete

* Change the timer's type, expires, and interval values to the given

[235] Fix | Delete

* values. If 'purge' is TRUE, any pending events from this timer

[236] Fix | Delete

* are purged from its task's event queue.

[237] Fix | Delete

*

[238] Fix | Delete

* Notes:

[239] Fix | Delete

*

[240] Fix | Delete

*\li If 'expires' is NULL, the epoch will be used.

[241] Fix | Delete

*

[242] Fix | Delete

*\li If 'interval' is NULL, the zero interval will be used.

[243] Fix | Delete

*

[244] Fix | Delete

* Requires:

[245] Fix | Delete

*

[246] Fix | Delete

*\li 'timer' is a valid timer

[247] Fix | Delete

*

[248] Fix | Delete

*\li The same requirements that isc_timer_create() imposes on 'type',

[249] Fix | Delete

* 'expires' and 'interval' apply.

[250] Fix | Delete

*

[251] Fix | Delete

* Ensures:

[252] Fix | Delete

*

[253] Fix | Delete

*\li An idle timeout will not be generated until at least Now + the

[254] Fix | Delete

* timer's interval if 'timer' is a once timer with a non-zero

[255] Fix | Delete

* interval.

[256] Fix | Delete

*

[257] Fix | Delete

* Returns:

[258] Fix | Delete

*

[259] Fix | Delete

*\li Success

[260] Fix | Delete

*\li No memory

[261] Fix | Delete

*\li Unexpected error

[262] Fix | Delete

*/

[263] Fix | Delete

[264] Fix | Delete

isc_result_t

[265] Fix | Delete

isc_timer_touch(isc_timer_t *timer);

[266] Fix | Delete

/*%<

[267] Fix | Delete

* Set the last-touched time of 'timer' to the current time.

[268] Fix | Delete

*

[269] Fix | Delete

* Requires:

[270] Fix | Delete

*

[271] Fix | Delete

*\li 'timer' is a valid once timer.

[272] Fix | Delete

*

[273] Fix | Delete

* Ensures:

[274] Fix | Delete

*

[275] Fix | Delete

*\li An idle timeout will not be generated until at least Now + the

[276] Fix | Delete

* timer's interval if 'timer' is a once timer with a non-zero

[277] Fix | Delete

* interval.

[278] Fix | Delete

*

[279] Fix | Delete

* Returns:

[280] Fix | Delete

*

[281] Fix | Delete

*\li Success

[282] Fix | Delete

*\li Unexpected error

[283] Fix | Delete

*/

[284] Fix | Delete

[285] Fix | Delete

void

[286] Fix | Delete

isc_timer_attach(isc_timer_t *timer, isc_timer_t **timerp);

[287] Fix | Delete

/*%<

[288] Fix | Delete

* Attach *timerp to timer.

[289] Fix | Delete

*

[290] Fix | Delete

* Requires:

[291] Fix | Delete

*

[292] Fix | Delete

*\li 'timer' is a valid timer.

[293] Fix | Delete

*

[294] Fix | Delete

*\li 'timerp' points to a NULL timer.

[295] Fix | Delete

*

[296] Fix | Delete

* Ensures:

[297] Fix | Delete

*

[298] Fix | Delete

*\li *timerp is attached to timer.

[299] Fix | Delete

*/

[300] Fix | Delete

[301] Fix | Delete

void

[302] Fix | Delete

isc_timer_detach(isc_timer_t **timerp);

[303] Fix | Delete

/*%<

[304] Fix | Delete

* Detach *timerp from its timer.

[305] Fix | Delete

*

[306] Fix | Delete

* Requires:

[307] Fix | Delete

*

[308] Fix | Delete

*\li 'timerp' points to a valid timer.

[309] Fix | Delete

*

[310] Fix | Delete

* Ensures:

[311] Fix | Delete

*

[312] Fix | Delete

*\li *timerp is NULL.

[313] Fix | Delete

*

[314] Fix | Delete

*\li If '*timerp' is the last reference to the timer,

[315] Fix | Delete

* then:

[316] Fix | Delete

*

[317] Fix | Delete

*\code

[318] Fix | Delete

* The timer will be shutdown

[319] Fix | Delete

*

[320] Fix | Delete

* The timer will detach from its task

[321] Fix | Delete

*

[322] Fix | Delete

* All resources used by the timer have been freed

[323] Fix | Delete

*

[324] Fix | Delete

* Any events already posted by the timer will be purged.

[325] Fix | Delete

* Therefore, if isc_timer_detach() is called in the context

[326] Fix | Delete

* of the timer's task, it is guaranteed that no more

[327] Fix | Delete

* timer event callbacks will run after the call.

[328] Fix | Delete

*\endcode

[329] Fix | Delete

*/

[330] Fix | Delete

[331] Fix | Delete

isc_timertype_t

[332] Fix | Delete

isc_timer_gettype(isc_timer_t *timer);

[333] Fix | Delete

/*%<

[334] Fix | Delete

* Return the timer type.

[335] Fix | Delete

*

[336] Fix | Delete

* Requires:

[337] Fix | Delete

*

[338] Fix | Delete

*\li 'timer' to be a valid timer.

[339] Fix | Delete

*/

[340] Fix | Delete

[341] Fix | Delete

isc_result_t

[342] Fix | Delete

isc_timermgr_createinctx(isc_mem_t *mctx, isc_appctx_t *actx,

[343] Fix | Delete

isc_timermgr_t **managerp);

[344] Fix | Delete

[345] Fix | Delete

isc_result_t

[346] Fix | Delete

isc_timermgr_create(isc_mem_t *mctx, isc_timermgr_t **managerp);

[347] Fix | Delete

/*%<

[348] Fix | Delete

* Create a timer manager. isc_timermgr_createinctx() also associates

[349] Fix | Delete

* the new manager with the specified application context.

[350] Fix | Delete

*

[351] Fix | Delete

* Notes:

[352] Fix | Delete

*

[353] Fix | Delete

*\li All memory will be allocated in memory context 'mctx'.

[354] Fix | Delete

*

[355] Fix | Delete

* Requires:

[356] Fix | Delete

*

[357] Fix | Delete

*\li 'mctx' is a valid memory context.

[358] Fix | Delete

*

[359] Fix | Delete

*\li 'managerp' points to a NULL isc_timermgr_t.

[360] Fix | Delete

*

[361] Fix | Delete

*\li 'actx' is a valid application context (for createinctx()).

[362] Fix | Delete

*

[363] Fix | Delete

* Ensures:

[364] Fix | Delete

*

[365] Fix | Delete

*\li '*managerp' is a valid isc_timermgr_t.

[366] Fix | Delete

*

[367] Fix | Delete

* Returns:

[368] Fix | Delete

*

[369] Fix | Delete

*\li Success

[370] Fix | Delete

*\li No memory

[371] Fix | Delete

*\li Unexpected error

[372] Fix | Delete

*/

[373] Fix | Delete

[374] Fix | Delete

void

[375] Fix | Delete

isc_timermgr_destroy(isc_timermgr_t **managerp);

[376] Fix | Delete

/*%<

[377] Fix | Delete

* Destroy a timer manager.

[378] Fix | Delete

*

[379] Fix | Delete

* Notes:

[380] Fix | Delete

*

[381] Fix | Delete

*\li This routine blocks until there are no timers left in the manager,

[382] Fix | Delete

* so if the caller holds any timer references using the manager, it

[383] Fix | Delete

* must detach them before calling isc_timermgr_destroy() or it will

[384] Fix | Delete

* block forever.

[385] Fix | Delete

*

[386] Fix | Delete

* Requires:

[387] Fix | Delete

*

[388] Fix | Delete

*\li '*managerp' is a valid isc_timermgr_t.

[389] Fix | Delete

*

[390] Fix | Delete

* Ensures:

[391] Fix | Delete

*

[392] Fix | Delete

*\li *managerp == NULL

[393] Fix | Delete

*

[394] Fix | Delete

*\li All resources used by the manager have been freed.

[395] Fix | Delete

*/

[396] Fix | Delete

[397] Fix | Delete

void isc_timermgr_poke(isc_timermgr_t *m);

[398] Fix | Delete

[399] Fix | Delete

/*%<

[400] Fix | Delete

* See isc_timermgr_create() above.

[401] Fix | Delete

*/

[402] Fix | Delete

typedef isc_result_t

[403] Fix | Delete

(*isc_timermgrcreatefunc_t)(isc_mem_t *mctx, isc_timermgr_t **managerp);

[404] Fix | Delete

[405] Fix | Delete

isc_result_t

[406] Fix | Delete

isc__timer_register(void);

[407] Fix | Delete

/*%<

[408] Fix | Delete

* Register a new timer management implementation and add it to the list of

[409] Fix | Delete

* supported implementations. This function must be called when a different

[410] Fix | Delete

* event library is used than the one contained in the ISC library.

[411] Fix | Delete

*/

[412] Fix | Delete

[413] Fix | Delete

isc_result_t

[414] Fix | Delete

isc_timer_register(isc_timermgrcreatefunc_t createfunc);

[415] Fix | Delete

/*%<

[416] Fix | Delete

* A short cut function that specifies the timer management module in the ISC

[417] Fix | Delete

* library for isc_timer_register(). An application that uses the ISC library

[418] Fix | Delete

* usually do not have to care about this function: it would call

[419] Fix | Delete

* isc_lib_register(), which internally calls this function.

[420] Fix | Delete

*/

[421] Fix | Delete

[422] Fix | Delete

ISC_LANG_ENDDECLS

[423] Fix | Delete

[424] Fix | Delete

#endif /* ISC_TIMER_H */

[425] Fix | Delete

[426] Fix | Delete