timer.h File Reference

Provides timers which are event sources in the task system. More...

#include <isc/types.h>
#include <isc/event.h>
#include <isc/eventclass.h>
#include <isc/lang.h>
#include <isc/time.h>

Go to the source code of this file.

Data Structures

struct isc_timerevent

struct isc_timermgrmethods_t

Timer and timer manager methods. More...

struct isc_timermethods_t

struct isc_timermgr

This structure is actually just the common prefix of a timer manager object implementation's version of an isc_timermgr_t. More...

struct isc_timer

This is the common prefix of a timer object. The same note as that for the timermgr structure applies. More...

Defines

#define ISC_TIMER_H   1

#define ISC_TIMEREVENT_FIRSTEVENT   (ISC_EVENTCLASS_TIMER + 0)

#define ISC_TIMEREVENT_TICK   (ISC_EVENTCLASS_TIMER + 1)

#define ISC_TIMEREVENT_IDLE   (ISC_EVENTCLASS_TIMER + 2)

#define ISC_TIMEREVENT_LIFE   (ISC_EVENTCLASS_TIMER + 3)

#define ISC_TIMEREVENT_LASTEVENT   (ISC_EVENTCLASS_TIMER + 65535)

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

#define ISCAPI_TIMERMGR_VALID(m)

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

#define ISCAPI_TIMER_VALID(s)

Typedefs

typedef struct isc_timerevent isc_timerevent_t

typedef isc_result_t(* isc_timermgrcreatefunc_t )(isc_mem_t *mctx, isc_timermgr_t **managerp)

Enumerations

enum isc_timertype_t {
  isc_timertype_undefined = -1, isc_timertype_ticker = 0, isc_timertype_once = 1, isc_timertype_limited = 2,
  isc_timertype_inactive = 3
}

Timer Type. More...

Functions

isc_result_t isc_timer_create (isc_timermgr_t *manager, isc_timertype_t type, const isc_time_t *expires, const isc_interval_t *interval, isc_task_t *task, isc_taskaction_t action, void *arg, isc_timer_t **timerp)

Create a new 'type' timer managed by 'manager'. The timers parameters are specified by 'expires' and 'interval'. Events will be posted to 'task' and when dispatched 'action' will be called with 'arg' as the arg value. The new timer is returned in 'timerp'.

isc_result_t isc_timer_reset (isc_timer_t *timer, isc_timertype_t type, const isc_time_t *expires, const isc_interval_t *interval, isc_boolean_t purge)

Change the timer's type, expires, and interval values to the given values. If 'purge' is TRUE, any pending events from this timer are purged from its task's event queue.

isc_result_t isc_timer_touch (isc_timer_t *timer)

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

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

Attach *timerp to timer.

void isc_timer_detach (isc_timer_t **timerp)

Detach *timerp from its timer.

isc_timertype_t isc_timer_gettype (isc_timer_t *timer)

Return the timer type.

isc_result_t isc_timermgr_createinctx (isc_mem_t *mctx, isc_appctx_t *actx, isc_timermgr_t **managerp)

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

Create a timer manager. isc_timermgr_createinctx() also associates the new manager with the specified application context.

void isc_timermgr_destroy (isc_timermgr_t **managerp)

Destroy a timer manager.

void isc_timermgr_poke (isc_timermgr_t *m)

See isc_timermgr_create() above.

isc_result_t isc__timer_register (void)

Register a new timer management implementation and add it to the list of supported implementations. This function must be called when a different event library is used than the one contained in the ISC library.

isc_result_t isc_timer_register (isc_timermgrcreatefunc_t createfunc)

A short cut function that specifies the timer management module in the ISC library for isc_timer_register(). An application that uses the ISC library usually do not have to care about this function: it would call isc_lib_register(), which internally calls this function.

Detailed Description

Provides timers which are event sources in the task system.

Three types of timers are supported:

'ticker' timers generate a periodic tick event.

'once' timers generate an idle timeout event if they are idle for too long, and generate a life timeout event if their lifetime expires. They are used to implement both (possibly expiring) idle timers and 'one-shot' timers.

'limited' timers generate a periodic tick event until they reach their lifetime when they generate a life timeout event.

'inactive' timers generate no events.

Timers can change type. It is typical to create a timer as an 'inactive' timer and then change it into a 'ticker' or 'once' timer.

MP: The module ensures appropriate synchronization of data structures it creates and manipulates. Clients of this module must not be holding a timer's task's lock when making a call that affects that timer. Failure to follow this rule can result in deadlock. The caller must ensure that isc_timermgr_destroy() is called only once for a given manager.

Reliability: No anticipated impact.

Resources: TBS

Security: No anticipated impact.

Standards: None.

Definition in file timer.h.

Define Documentation

#define ISC_TIMER_H 1

Definition at line 21 of file timer.h.

#define ISC_TIMEREVENT_FIRSTEVENT (ISC_EVENTCLASS_TIMER + 0)

Definition at line 101 of file timer.h.

Referenced by destroy(), and isc__timer_reset().

#define ISC_TIMEREVENT_TICK (ISC_EVENTCLASS_TIMER + 1)

Definition at line 102 of file timer.h.

Referenced by acache_cleaning_timer_action(), cleaning_timer_action(), dispatch(), and req_timeout().

#define ISC_TIMEREVENT_IDLE (ISC_EVENTCLASS_TIMER + 2)

Definition at line 103 of file timer.h.

Referenced by client_delay(), client_timeout(), connect_timeout(), dispatch(), and force_timeout().

#define ISC_TIMEREVENT_LIFE (ISC_EVENTCLASS_TIMER + 3)

Definition at line 104 of file timer.h.

Referenced by client_delay(), client_timeout(), dispatch(), and fctx_timeout().

#define ISC_TIMEREVENT_LASTEVENT (ISC_EVENTCLASS_TIMER + 65535)

Definition at line 105 of file timer.h.

Referenced by destroy(), and isc__timer_reset().

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

Definition at line 145 of file timer.h.

Referenced by isc__timermgr_create().

#define ISCAPI_TIMERMGR_VALID ( m )

Value:

((m) != NULL && \
                                         (m)->magic == ISCAPI_TIMERMGR_MAGIC)

Definition at line 146 of file timer.h.

Referenced by isc_timer_create(), and isc_timermgr_destroy().

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

Definition at line 159 of file timer.h.

Referenced by isc__timer_create().

#define ISCAPI_TIMER_VALID ( s )

Value:

((s) != NULL && \
                                 (s)->magic == ISCAPI_TIMER_MAGIC)

Definition at line 160 of file timer.h.

Referenced by isc_timer_attach(), isc_timer_detach(), isc_timer_reset(), and isc_timer_touch().

Typedef Documentation

typedef struct isc_timerevent isc_timerevent_t

typedef isc_result_t(* isc_timermgrcreatefunc_t)(isc_mem_t *mctx, isc_timermgr_t **managerp)

Definition at line 410 of file timer.h.

Enumeration Type Documentation

enum isc_timertype_t

Timer Type.

Enumerator:

isc_timertype_undefined	Undefined.
isc_timertype_ticker	Ticker.
isc_timertype_once	Once.
isc_timertype_limited	Limited.
isc_timertype_inactive	Inactive.

Definition at line 88 of file timer.h.

Function Documentation

isc_result_t isc_timer_create	(	isc_timermgr_t *	manager,
		isc_timertype_t	type,
		const isc_time_t *	expires,
		const isc_interval_t *	interval,
		isc_task_t *	task,
		isc_taskaction_t	action,
		void *	arg,
		isc_timer_t **	timerp
	)

Create a new 'type' timer managed by 'manager'. The timers parameters are specified by 'expires' and 'interval'. Events will be posted to 'task' and when dispatched 'action' will be called with 'arg' as the arg value. The new timer is returned in 'timerp'.

Notes:

For ticker timers, the timer will generate a 'tick' event every 'interval' seconds. The value of 'expires' is ignored.

For once timers, 'expires' specifies the time when a life timeout event should be generated. If 'expires' is 0 (the epoch), then no life timeout will be generated. 'interval' specifies how long the timer can be idle before it generates an idle timeout. If 0, then no idle timeout will be generated.

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

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

Requires:

'manager' is a valid manager

'task' is a valid task

'action' is a valid action

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

'interval' points to a valid interval, or is NULL.

type == isc_timertype_inactive || ('expires' and 'interval' are not both 0)

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

Ensures:

'*timerp' is attached to the newly created timer

The timer is attached to the task

An idle timeout will not be generated until at least Now + the timer's interval if 'timer' is a once timer with a non-zero interval.

Returns:

Success
No memory
Unexpected error

Definition at line 1131 of file timer.c.

References isc__timer_create(), isc_bind9, ISCAPI_TIMERMGR_VALID, isc_timermgr::methods, REQUIRE, and isc_timermgrmethods_t::timercreate.

Referenced by acache_cleaner_init(), bringup_timer(), cache_cleaner_init(), client_create(), dns_request_createraw4(), dns_request_createvia4(), dns_resolver_create(), dns_zone_link(), dns_zonemgr_managezone(), fctx_create(), isc_ratelimiter_create(), newconnection(), ns_client_send(), run_server(), settimer(), and xfrin_create().

isc_result_t isc_timer_reset	(	isc_timer_t *	timer,
		isc_timertype_t	type,
		const isc_time_t *	expires,
		const isc_interval_t *	interval,
		isc_boolean_t	purge
	)

Change the timer's type, expires, and interval values to the given values. If 'purge' is TRUE, any pending events from this timer are purged from its task's event queue.

Notes:

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

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

Requires:

'timer' is a valid timer

The same requirements that isc_timer_create() imposes on 'type', 'expires' and 'interval' apply.

Ensures:

An idle timeout will not be generated until at least Now + the timer's interval if 'timer' is a once timer with a non-zero interval.

Returns:

Success
No memory
Unexpected error

Definition at line 1173 of file timer.c.

References isc__timer_reset(), isc_bind9, ISCAPI_TIMER_VALID, isc_timer::methods, REQUIRE, and isc_timermethods_t::reset.

Referenced by dns_acache_setcleaninginterval(), dns_cache_setcleaninginterval(), dns_ntatable_covered(), dns_resolver_shutdown(), dns_timer_setidle(), exit_check(), fctx_sendevents(), fctx_startidletimer(), fctx_starttimer(), fctx_stoptimer(), fetch_done(), isc_ratelimiter_enqueue(), isc_ratelimiter_release(), isc_ratelimiter_setinterval(), isc_ratelimiter_shutdown(), isc_ratelimiter_stall(), load_configuration(), ns_client_settimeout(), nta_detach(), ratelimiter_tick(), recv_done(), set_timer(), spillattimer_countdown(), and zone_settimer().

isc_result_t isc_timer_touch ( isc_timer_t * timer )

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

Requires:

'timer' is a valid once timer.

Ensures:

An idle timeout will not be generated until at least Now + the timer's interval if 'timer' is a once timer with a non-zero interval.

Returns:

Success
Unexpected error

Definition at line 1187 of file timer.c.

References isc__timer_touch(), isc_bind9, ISCAPI_TIMER_VALID, isc_timer::methods, REQUIRE, and isc_timermethods_t::touch.

Referenced by recv_done(), resquery_response(), xfrin_recv_done(), and xfrout_senddone().

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

Attach *timerp to timer.

Requires:

'timer' is a valid timer.

'timerp' points to a NULL timer.

Ensures:

*timerp is attached to timer.

Definition at line 1148 of file timer.c.

References isc_timermethods_t::attach, ENSURE, isc__timer_attach(), isc_bind9, ISCAPI_TIMER_VALID, isc_timer::methods, and REQUIRE.

void isc_timer_detach ( isc_timer_t ** timerp )

Detach *timerp from its timer.

Requires:

'timerp' points to a valid timer.

Ensures:

*timerp is NULL.

If '*timerp' is the last reference to the timer, then:

                The timer will be shutdown

                The timer will detach from its task

                All resources used by the timer have been freed

                Any events already posted by the timer will be purged.
                Therefore, if isc_timer_detach() is called in the context
                of the timer's task, it is guaranteed that no more
                timer event callbacks will run after the call.
 *

Definition at line 1161 of file timer.c.

References ENSURE, isc__timer_detach(), isc_bind9, ISCAPI_TIMER_VALID, and REQUIRE.

Referenced by acache_cleaner_init(), acache_cleaner_shutdown_action(), bringup_timer(), cache_cleaner_init(), cancel_all(), cancel_lookup(), cleaner_shutdown_action(), client_create(), client_delay(), control_timeout(), destroy(), destroy_lookup(), dns_ntatable_covered(), dns_resolver_create(), exit_check(), fctx_destroy(), flush_lookup_list(), force_timeout(), isc_ratelimiter_shutdown(), maybe_free(), maybe_free_connection(), newconnection(), nta_detach(), req_cancel(), req_destroy(), shutdown_server(), xfrin_create(), and zone_shutdown().

isc_timertype_t isc_timer_gettype ( isc_timer_t * timer )

Return the timer type.

Requires:

'timer' to be a valid timer.

Definition at line 577 of file timer.c.

References isc__timer::lock, LOCK, REQUIRE, isc__timer::type, UNLOCK, and VALID_TIMER.

isc_result_t isc_timermgr_createinctx	(	isc_mem_t *	mctx,
		isc_appctx_t *	actx,
		isc_timermgr_t **	managerp
	)

Definition at line 1083 of file timer.c.

References isc_appctx_settimermgr(), ISC_R_SUCCESS, LOCK, REQUIRE, and UNLOCK.

Referenced by dns_client_create().

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

Create a timer manager. isc_timermgr_createinctx() also associates the new manager with the specified application context.

Notes:

All memory will be allocated in memory context 'mctx'.

Requires:

'mctx' is a valid memory context.

'managerp' points to a NULL isc_timermgr_t.

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

Ensures:

'*managerp' is a valid isc_timermgr_t.

Returns:

Success
No memory
Unexpected error

Definition at line 1102 of file timer.c.

References isc__timermgr_create(), isc_bind9, LOCK, REQUIRE, and UNLOCK.

Referenced by create_managers(), setup_libs(), and setup_system().

void isc_timermgr_destroy ( isc_timermgr_t ** managerp )

Destroy a timer manager.

Notes:

This routine blocks until there are no timers left in the manager, so if the caller holds any timer references using the manager, it must detach them before calling isc_timermgr_destroy() or it will block forever.

Requires:

'*managerp' is a valid isc_timermgr_t.

Ensures:

*managerp == NULL

All resources used by the manager have been freed.

Definition at line 1119 of file timer.c.

References ENSURE, isc__timermgr_destroy(), isc_bind9, ISCAPI_TIMERMGR_VALID, and REQUIRE.

Referenced by cleanup(), cleanup_managers(), destroy_libs(), destroy_managers(), destroyclient(), and dns_client_create().

void isc_timermgr_poke ( isc_timermgr_t * m )

See isc_timermgr_create() above.

Definition at line 937 of file timer.c.

References REQUIRE, SIGNAL, UNUSED, and VALID_MANAGER.

Referenced by ns_control_docommand().

isc_result_t isc__timer_register ( void )

Register a new timer management implementation and add it to the list of supported implementations. This function must be called when a different event library is used than the one contained in the ISC library.

Definition at line 1053 of file timer.c.

References isc__timermgr_create(), and isc_timer_register().

Referenced by do_register().

isc_result_t isc_timer_register ( isc_timermgrcreatefunc_t createfunc )

A short cut function that specifies the timer management module in the ISC library for isc_timer_register(). An application that uses the ISC library usually do not have to care about this function: it would call isc_lib_register(), which internally calls this function.

Definition at line 1067 of file timer.c.

References initialize(), isc_once_do, ISC_R_EXISTS, ISC_R_SUCCESS, LOCK, RUNTIME_CHECK, and UNLOCK.

Referenced by isc__timer_register().

Generated on Tue Apr 28 17:41:16 2015 by Doxygen 1.5.4 for BIND9 Internals 9.11.0pre-alpha


Data Structures
struct	isc_timerevent
struct	isc_timermgrmethods_t
	Timer and timer manager methods. More...
struct	isc_timermethods_t
struct	isc_timermgr
	This structure is actually just the common prefix of a timer manager object implementation's version of an isc_timermgr_t. More...
struct	isc_timer
	This is the common prefix of a timer object. The same note as that for the timermgr structure applies. More...
Defines
#define	ISC_TIMER_H 1
#define	ISC_TIMEREVENT_FIRSTEVENT (ISC_EVENTCLASS_TIMER + 0)
#define	ISC_TIMEREVENT_TICK (ISC_EVENTCLASS_TIMER + 1)
#define	ISC_TIMEREVENT_IDLE (ISC_EVENTCLASS_TIMER + 2)
#define	ISC_TIMEREVENT_LIFE (ISC_EVENTCLASS_TIMER + 3)
#define	ISC_TIMEREVENT_LASTEVENT (ISC_EVENTCLASS_TIMER + 65535)
#define	ISCAPI_TIMERMGR_MAGIC ISC_MAGIC('A','t','m','g')
#define	ISCAPI_TIMERMGR_VALID(m)
#define	ISCAPI_TIMER_MAGIC ISC_MAGIC('A','t','m','r')
#define	ISCAPI_TIMER_VALID(s)
Typedefs
typedef struct isc_timerevent	isc_timerevent_t
typedef isc_result_t(*	isc_timermgrcreatefunc_t )(isc_mem_t mctx, isc_timermgr_t *managerp)
Enumerations
enum	isc_timertype_t { isc_timertype_undefined = -1, isc_timertype_ticker = 0, isc_timertype_once = 1, isc_timertype_limited = 2, isc_timertype_inactive = 3 }
	Timer Type. More...
Functions
isc_result_t	isc_timer_create (isc_timermgr_t manager, isc_timertype_t type, const isc_time_t expires, const isc_interval_t interval, isc_task_t task, isc_taskaction_t action, void arg, isc_timer_t *timerp)
	Create a new 'type' timer managed by 'manager'. The timers parameters are specified by 'expires' and 'interval'. Events will be posted to 'task' and when dispatched 'action' will be called with 'arg' as the arg value. The new timer is returned in 'timerp'.
isc_result_t	isc_timer_reset (isc_timer_t timer, isc_timertype_t type, const isc_time_t expires, const isc_interval_t *interval, isc_boolean_t purge)
	Change the timer's type, expires, and interval values to the given values. If 'purge' is TRUE, any pending events from this timer are purged from its task's event queue.
isc_result_t	isc_timer_touch (isc_timer_t *timer)
	Set the last-touched time of 'timer' to the current time.
void	isc_timer_attach (isc_timer_t timer, isc_timer_t *timerp)
	Attach *timerp to timer.
void	isc_timer_detach (isc_timer_t **timerp)
	Detach *timerp from its timer.
isc_timertype_t	isc_timer_gettype (isc_timer_t *timer)
	Return the timer type.
isc_result_t	isc_timermgr_createinctx (isc_mem_t mctx, isc_appctx_t actx, isc_timermgr_t **managerp)
isc_result_t	isc_timermgr_create (isc_mem_t mctx, isc_timermgr_t *managerp)
	Create a timer manager. isc_timermgr_createinctx() also associates the new manager with the specified application context.
void	isc_timermgr_destroy (isc_timermgr_t **managerp)
	Destroy a timer manager.
void	isc_timermgr_poke (isc_timermgr_t *m)
	See isc_timermgr_create() above.
isc_result_t	isc__timer_register (void)
	Register a new timer management implementation and add it to the list of supported implementations. This function must be called when a different event library is used than the one contained in the ISC library.
isc_result_t	isc_timer_register (isc_timermgrcreatefunc_t createfunc)
	A short cut function that specifies the timer management module in the ISC library for isc_timer_register(). An application that uses the ISC library usually do not have to care about this function: it would call isc_lib_register(), which internally calls this function.