periodic.c File Reference

Generic backend for handling periodic events. More...

#include "core/or/or.h"
#include "lib/evloop/compat_libevent.h"
#include "app/config/config.h"
#include "core/mainloop/mainloop.h"
#include "core/mainloop/periodic.h"

Go to the source code of this file.

Macros
#define	LONGEST_TIMER_PERIOD   (30 * 86400)

Functions
static void	periodic_event_set_interval (periodic_event_item_t *event, time_t next_interval)
static void	periodic_event_dispatch (mainloop_event_t *ev, void *data)
void	periodic_event_reschedule (periodic_event_item_t *event)
void	periodic_event_connect (periodic_event_item_t *event)
void	periodic_event_launch (periodic_event_item_t *event)
static void	periodic_event_disconnect (periodic_event_item_t *event)
void	periodic_event_enable (periodic_event_item_t *event)
void	periodic_event_disable (periodic_event_item_t *event)
void	periodic_event_schedule_and_disable (periodic_event_item_t *event)
void	periodic_events_register (periodic_event_item_t *item)
void	periodic_events_connect_all (void)
void	periodic_events_reset_all (void)
periodic_event_item_t *	periodic_events_find (const char *name)
void	periodic_events_rescan_by_roles (int roles, bool net_disabled)
void	periodic_events_disconnect_all (void)
int	safe_timer_diff (time_t now, time_t next)

Variables
static const int	MAX_INTERVAL = 10 * 365 * 86400
static smartlist_t *	the_periodic_events = NULL

Detailed Description

Generic backend for handling periodic events.

The events in this module are used to track items that need to fire once every N seconds, possibly picking a new interval each time that they fire. See periodic_events[] in mainloop.c for examples.

This module manages a global list of periodic_event_item_t objects, each corresponding to a single event. To register an event, pass it to periodic_events_register() when initializing your subsystem.

Registering an event makes the periodic event subsystem know about it, but doesn't cause the event to get created immediately. Before the event can be started, periodic_event_connect_all() must be called by mainloop.c to connect all the events to Libevent.

We expect that periodic_event_item_t objects will be statically allocated; we set them up and tear them down here, but we don't take ownership of them.

Definition in file periodic.c.

Function Documentation

periodic_event_connect()

void periodic_event_connect

(

periodic_event_item_t *

event

)

Connects a periodic event to the Libevent backend. Does not launch the event immediately.

Definition at line 117 of file periodic.c.

Referenced by periodic_events_connect_all().

periodic_event_disable()

void periodic_event_disable

(

periodic_event_item_t *

event

)

Disable the given event which means the event is destroyed and then the event's enabled flag is unset. This can be called for an event that is already disabled.

Definition at line 185 of file periodic.c.

Referenced by periodic_event_disconnect().

periodic_event_disconnect()

static void periodic_event_disconnect ( periodic_event_item_t *  event )

static

Disconnect and unregister the periodic event in event

Definition at line 151 of file periodic.c.

Referenced by periodic_events_disconnect_all().

periodic_event_dispatch()

static void periodic_event_dispatch ( mainloop_event_t *  ev, void *  data  )

static

Wraps dispatches for periodic events, data will be a pointer to the event that needs to be called

Definition at line 61 of file periodic.c.

periodic_event_enable()

void periodic_event_enable

(

periodic_event_item_t *

event

)

Enable the given event by setting its "enabled" flag and scheduling it to run immediately in the event loop. This can be called for an event that is already enabled.

Definition at line 168 of file periodic.c.

periodic_event_launch()

void periodic_event_launch

(

periodic_event_item_t *

event

)

Handles initial dispatch for periodic events. It should happen 1 second after the events are created to mimic behaviour before #3199's refactor

Definition at line 132 of file periodic.c.

periodic_event_reschedule()

void periodic_event_reschedule

(

periodic_event_item_t *

event

)

Schedules event to run as soon as possible from now.

Definition at line 106 of file periodic.c.

Referenced by periodic_events_reset_all(), and reschedule_descriptor_update_check().

periodic_event_schedule_and_disable()

void periodic_event_schedule_and_disable

(

periodic_event_item_t *

event

)

Disable an event, then schedule it to run once. Do nothing if the event was already disabled.

Definition at line 201 of file periodic.c.

periodic_event_set_interval()

static void periodic_event_set_interval ( periodic_event_item_t *  event, time_t  next_interval  )

static

Set the event event to run in next_interval seconds from now.

Definition at line 48 of file periodic.c.

periodic_events_connect_all()

void periodic_events_connect_all

(

void

)

Make all registered periodic events connect to the libevent backend.

Definition at line 234 of file periodic.c.

Referenced by do_main_loop().

periodic_events_disconnect_all()

void periodic_events_disconnect_all

(

void

)

Invoked at shutdown: disconnect and unregister all periodic events.

Does not free the periodic_event_item_t object themselves, because we do not own them.

Definition at line 331 of file periodic.c.

periodic_events_find()

periodic_event_item_t* periodic_events_find

(

const char *

name

)

Return the registered periodic event whose name is name. Return NULL if no such event is found.

Definition at line 272 of file periodic.c.

periodic_events_register()

void periodic_events_register

(

periodic_event_item_t *

item

)

Add item to the list of periodic events.

Note that item should be statically allocated: we do not take ownership of it.

Definition at line 219 of file periodic.c.

periodic_events_rescan_by_roles()

void periodic_events_rescan_by_roles	(	int	roles,
		bool	net_disabled
	)

Start or stop registered periodic events, depending on our current set of roles.

Invoked when our list of roles, or the net_disabled flag has changed.

Definition at line 291 of file periodic.c.

Referenced by rescan_periodic_events().

periodic_events_reset_all()

void periodic_events_reset_all

(

void

)

Reset all the registered periodic events so we'll do all our actions again as if we just started up.

Useful if our clock just moved back a long time from the future, so we don't wait until that future arrives again before acting.

Definition at line 254 of file periodic.c.

Referenced by reset_all_main_loop_timers().

safe_timer_diff()

int safe_timer_diff	(	time_t	now,
		time_t	next
	)

Helper: Return the number of seconds between now and next, clipped to the range [1 second, LONGEST_TIMER_PERIOD].

We use this to answer the question, "how many seconds is it from now until next" in periodic timer callbacks. Don't use it for other purposes

Definition at line 351 of file periodic.c.

Referenced by downrate_stability_callback().

Variable Documentation

MAX_INTERVAL

const int MAX_INTERVAL = 10 * 365 * 86400

static

We disable any interval greater than this number of seconds, on the grounds that it is probably an absolute time mistakenly passed in as a relative time.

Definition at line 37 of file periodic.c.

Referenced by periodic_event_set_interval().

the_periodic_events

smartlist_t* the_periodic_events = NULL

static

Global list of periodic events that have been registered with periodic_event_register.

Definition at line 43 of file periodic.c.

Referenced by periodic_events_connect_all(), periodic_events_disconnect_all(), periodic_events_find(), periodic_events_register(), periodic_events_rescan_by_roles(), and periodic_events_reset_all().