timers.c File Reference

Wrapper around William Ahern's fast hierarchical timer wheel implementation, to tie it in with a libevent backend. More...

#include "orconfig.h"
#include "lib/evloop/compat_libevent.h"
#include "lib/evloop/timers.h"
#include "lib/intmath/muldiv.h"
#include "lib/log/log.h"
#include "lib/log/util_bug.h"
#include "lib/malloc/malloc.h"
#include "lib/time/compat_time.h"
#include "ext/timeouts/timeout.c"

Go to the source code of this file.

Data Structures
struct	timeout_cb_t

Macros
#define	TOR_TIMERS_PRIVATE
#define	TIMEOUT_PUBLIC   static
#define	TIMEOUT_DISABLE_INTERVALS
#define	TIMEOUT_DISABLE_RELATIVE_ACCESS
#define	TIMEOUT_CB_OVERRIDE
#define	WHEEL_NUM   5
#define	USEC_PER_TICK   100
#define	USEC_PER_SEC   1000000
#define	MIN_CHECK_SECONDS   3600
#define	MIN_CHECK_TICKS    (((timeout_t)MIN_CHECK_SECONDS) * (1000000 / USEC_PER_TICK))

Functions
static timeout_t	tv_to_timeout (const struct timeval *tv)
static void	timeout_to_tv (timeout_t t, struct timeval *tv_out)
static void	timer_advance_to_cur_time (const monotime_t *now)
static void	libevent_timer_reschedule (void)
STATIC void	timers_run_pending (void)
static void	libevent_timer_callback (mainloop_event_t *ev, void *arg)
void	timers_initialize (void)
void	timers_shutdown (void)
tor_timer_t *	timer_new (timer_cb_fn_t cb, void *arg)
void	timer_free_ (tor_timer_t *t)
void	timer_set_cb (tor_timer_t *t, timer_cb_fn_t cb, void *arg)
void	timer_get_cb (const tor_timer_t *t, timer_cb_fn_t *cb_out, void **arg_out)
void	timer_schedule (tor_timer_t *t, const struct timeval *tv)
void	timer_disable (tor_timer_t *t)

Variables
static struct timeouts *	global_timeouts = NULL
static struct mainloop_event_t *	global_timer_event = NULL
static monotime_t	start_of_time

Detailed Description

Wrapper around William Ahern's fast hierarchical timer wheel implementation, to tie it in with a libevent backend.

Only use these functions from the main thread.

The main advantage of tor_timer_t over using libevent's timers is that they're way more efficient if we need to have thousands or millions of them. For more information, see https://www.25thandclement.com/~william/projects/timeout.c.html

Periodic timers are available in the backend, but I've turned them off. We can turn them back on if needed.

Definition in file timers.c.

Macro Definition Documentation

MIN_CHECK_SECONDS

#define MIN_CHECK_SECONDS   3600

Check at least once every N seconds.

Definition at line 107 of file timers.c.

MIN_CHECK_TICKS

#define MIN_CHECK_TICKS    (((timeout_t)MIN_CHECK_SECONDS) * (1000000 / USEC_PER_TICK))

Check at least once every N ticks.

Definition at line 110 of file timers.c.

TIMEOUT_CB_OVERRIDE

#define TIMEOUT_CB_OVERRIDE

Definition at line 74 of file timers.c.

TIMEOUT_DISABLE_INTERVALS

#define TIMEOUT_DISABLE_INTERVALS

Definition at line 69 of file timers.c.

TIMEOUT_DISABLE_RELATIVE_ACCESS

#define TIMEOUT_DISABLE_RELATIVE_ACCESS

Definition at line 72 of file timers.c.

TIMEOUT_PUBLIC

#define TIMEOUT_PUBLIC   static

Definition at line 66 of file timers.c.

TOR_TIMERS_PRIVATE

#define TOR_TIMERS_PRIVATE

Definition at line 32 of file timers.c.

USEC_PER_SEC

#define USEC_PER_SEC   1000000

One million microseconds in a second

Definition at line 104 of file timers.c.

USEC_PER_TICK

#define USEC_PER_TICK   100

We need to choose this value carefully. Because we're using timer wheels, it actually costs us to have extra resolution we don't use. So for now, I'm going to define our resolution as .1 msec, and hope that's good enough.

Note that two of the most popular libevent backends (epoll without timerfd, and windows select), simply can't support sub-millisecond resolution, do this is optimistic for a lot of users.

Definition at line 101 of file timers.c.

WHEEL_NUM

#define WHEEL_NUM   5

Definition at line 79 of file timers.c.

Function Documentation

libevent_timer_callback()

static void libevent_timer_callback ( mainloop_event_t *  ev, void *  arg  )

static

Invoked when the libevent timer has expired: see which tor_timer_t events have fired, activate their callbacks, and reschedule the libevent timer.

Definition at line 190 of file timers.c.

libevent_timer_reschedule()

static void libevent_timer_reschedule ( void  )

static

Adjust the time at which the libevent timer should fire based on the next-expiring time in global_timeouts

Definition at line 155 of file timers.c.

Referenced by libevent_timer_callback().

timeout_to_tv()

static void timeout_to_tv ( timeout_t  t, struct timeval *  tv_out  )

static

Convert the timeout in t to a timeval in tv_out. Only use this for delays, not absolute times.

Definition at line 132 of file timers.c.

timer_advance_to_cur_time()

static void timer_advance_to_cur_time ( const monotime_t *  now )

static

Update the timer tv to the current time in tv.

Definition at line 143 of file timers.c.

Referenced by libevent_timer_reschedule(), and timers_run_pending().

timer_disable()

void timer_disable

(

tor_timer_t *

t

)

Cancel the timer t if it is currently scheduled. (It's okay to call this on an unscheduled timer.

Definition at line 326 of file timers.c.

timer_free_()

void timer_free_

(

tor_timer_t *

t

)

Release all storage held by t, and unschedule it if was already scheduled.

Definition at line 263 of file timers.c.

timer_get_cb()

void timer_get_cb	(	const tor_timer_t *	t,
		timer_cb_fn_t *	cb_out,
		void **	arg_out
	)

Set *cb_out (if provided) to this timer's callback function, and *arg_out (if provided) to this timer's callback argument.

Definition at line 287 of file timers.c.

timer_new()

tor_timer_t * timer_new	(	timer_cb_fn_t	cb,
		void *	arg
	)

Allocate and return a new timer, with given callback and argument.

Definition at line 250 of file timers.c.

timer_schedule()

void timer_schedule	(	tor_timer_t *	t,
		const struct timeval *	tv
	)

Schedule the timer t to fire at the current time plus a delay of delay microseconds. All times are relative to monotime_get().

Definition at line 301 of file timers.c.

timer_set_cb()

void timer_set_cb	(	tor_timer_t *	t,
		timer_cb_fn_t	cb,
		void *	arg
	)

Change the callback and argument associated with a timer t.

Definition at line 276 of file timers.c.

timers_initialize()

void timers_initialize

(

void

)

Initialize the timers subsystem. Requires that libevent has already been initialized.

Definition at line 205 of file timers.c.

timers_run_pending()

STATIC void timers_run_pending

(

void

)

Run the callback of every timer that has expired, based on the current output of monotime_get().

Definition at line 173 of file timers.c.

Referenced by libevent_timer_callback().

timers_shutdown()

void timers_shutdown

(

void

)

Release all storage held in the timers subsystem. Does not fire timers.

Definition at line 234 of file timers.c.

Referenced by tor_cleanup().

tv_to_timeout()

static timeout_t tv_to_timeout ( const struct timeval *  tv )

static

Convert the timeval in tv to a timeout_t, and return it.

The output resolution is set by USEC_PER_TICK. Only use this to convert delays to number of ticks; the time represented by 0 is undefined.

Definition at line 120 of file timers.c.

Variable Documentation

global_timeouts

struct timeouts* global_timeouts = NULL

static

Definition at line 88 of file timers.c.

global_timer_event

struct mainloop_event_t* global_timer_event = NULL

static

Definition at line 89 of file timers.c.

start_of_time

monotime_t start_of_time

static

Definition at line 91 of file timers.c.