Functions to close listeners, stop allowing new circuits, etc in preparation for closing down or going dormant; and to track bandwidth and time intervals to know when to hibernate and when to stop hibernating. More...

#include "core/or/or.h"
#include "core/or/channel.h"
#include "core/or/channeltls.h"
#include "app/config/config.h"
#include "core/mainloop/connection.h"
#include "core/or/connection_edge.h"
#include "core/or/connection_or.h"
#include "feature/control/control_events.h"
#include "lib/crypt_ops/crypto_rand.h"
#include "lib/defs/time.h"
#include "feature/hibernate/hibernate.h"
#include "core/mainloop/mainloop.h"
#include "feature/relay/router.h"
#include "app/config/statefile.h"
#include "lib/evloop/compat_libevent.h"
#include "core/or/or_connection_st.h"
#include "app/config/or_state_st.h"

Macros
#define	HIBERNATE_PRIVATE

#define	MIN_TIME_FOR_MEASUREMENT (1800)

#define	NOTE_INTERVAL (600)

#define	NOTE_BYTES (2010241024)

#define	ROUND_UP(x) (((x) + 0x3ff) & ~0x3ff)

#define	SOFT_LIM_PCT (.95)

#define	SOFT_LIM_BYTES (50010241024)

#define	SOFT_LIM_MINUTES (3*60)

Enumerations
enum	time_unit_t { UNIT_MONTH =1 , UNIT_WEEK =2 , UNIT_DAY =3 }

Functions
static const char *	hibernate_state_to_string (hibernate_state_t state)

static void	reset_accounting (time_t now)

static int	read_bandwidth_usage (void)

static time_t	start_of_accounting_period_after (time_t now)

static time_t	start_of_accounting_period_containing (time_t now)

static void	accounting_set_wakeup_time (void)

static void	on_hibernate_state_change (hibernate_state_t prev_state)

static void	hibernate_schedule_wakeup_event (time_t now, time_t end_time)

static void	wakeup_event_callback (mainloop_event_t ev, void data)

int	accounting_parse_options (const or_options_t *options, int validate_only)

int	accounting_is_enabled (const or_options_t *options)

int	accounting_get_interval_length (void)

time_t	accounting_get_end_time (void)

void	accounting_add_bytes (size_t n_read, size_t n_written, int seconds)

static time_t	edge_of_accounting_period_containing (time_t now, int get_end)

static long	length_of_accounting_period_containing (time_t now)

void	configure_accounting (time_t now)

uint64_t	get_accounting_bytes (void)

static void	update_expected_bandwidth (void)

static int	time_to_record_bandwidth_usage (time_t now)

void	accounting_run_housekeeping (time_t now)

int	accounting_record_bandwidth_usage (time_t now, or_state_t *state)

static int	hibernate_hard_limit_reached (void)

static int	hibernate_soft_limit_reached (void)

static void	hibernate_begin (hibernate_state_t new_state, time_t now)

static void	hibernate_end (hibernate_state_t new_state)

void	hibernate_begin_shutdown (void)

int	we_are_hibernating (void)

int	we_are_fully_hibernating (void)

static void	hibernate_go_dormant (time_t now)

static void	hibernate_end_time_elapsed (time_t now)

void	consider_hibernation (time_t now)

int	getinfo_helper_accounting (control_connection_t conn, const char question, char answer, const char errmsg)

void	accounting_free_all (void)

Variables
static hibernate_state_t	hibernate_state = HIBERNATE_STATE_INITIAL

static time_t	hibernate_end_time = 0

static time_t	shutdown_time = 0

static mainloop_event_t *	wakeup_event = NULL

static uint64_t	n_bytes_read_in_interval = 0

static uint64_t	n_bytes_written_in_interval = 0

static uint32_t	n_seconds_active_in_interval = 0

static int	n_seconds_to_hit_soft_limit = 0

static time_t	soft_limit_hit_at = 0

static uint64_t	n_bytes_at_soft_limit = 0

static time_t	interval_start_time = 0

static time_t	interval_end_time = 0

static time_t	interval_wakeup_time = 0

static uint64_t	expected_bandwidth_usage = 0

static time_unit_t	cfg_unit = UNIT_MONTH


static int	cfg_start_day = 0

static int	cfg_start_hour = 0

static int	cfg_start_min = 0

Detailed Description

Functions to close listeners, stop allowing new circuits, etc in preparation for closing down or going dormant; and to track bandwidth and time intervals to know when to hibernate and when to stop hibernating.

Ordinarily a Tor relay is "Live".

A live relay can stop accepting connections for one of two reasons: either it is trying to conserve bandwidth because of bandwidth accounting rules ("soft hibernation"), or it is about to shut down ("exiting").

Definition in file hibernate.c.

Enumeration Type Documentation

◆ time_unit_t

enum time_unit_t

Possible accounting periods.

Definition at line 80 of file hibernate.c.

Function Documentation

◆ accounting_add_bytes()

void accounting_add_bytes	(	size_t	n_read,
		size_t	n_written,
		int	seconds
	)

Called from connection.c to tell us that seconds seconds have passed, n_read bytes have been read, and n_written bytes have been written.

Definition at line 331 of file hibernate.c.

Referenced by record_num_bytes_transferred_impl().

◆ accounting_free_all()

void accounting_free_all ( void )

Free all resources held by the accounting module

Definition at line 1254 of file hibernate.c.

◆ accounting_get_end_time()

time_t accounting_get_end_time ( void )

Return the time at which the current accounting interval will end.

Definition at line 322 of file hibernate.c.

◆ accounting_get_interval_length()

int accounting_get_interval_length ( void )

If accounting is enabled, return how long (in seconds) this interval lasts.

Definition at line 315 of file hibernate.c.

Referenced by router_should_be_dirserver().

◆ accounting_is_enabled()

int accounting_is_enabled ( const or_options_t * options )

If we want to manage the accounting system and potentially hibernate, return 1, else return 0.

Definition at line 305 of file hibernate.c.

Referenced by record_num_bytes_transferred_impl(), router_should_be_dirserver(), second_elapsed_callback(), and tor_cleanup().

◆ accounting_parse_options()

int accounting_parse_options	(	const or_options_t *	options,
		int	validate_only
	)

Configure accounting start/end time settings based on options->AccountingStart. Return 0 on success, -1 on failure. If validate_only is true, do not change the current settings.

Definition at line 190 of file hibernate.c.

Referenced by options_act_relay_accounting().

◆ accounting_record_bandwidth_usage()

int accounting_record_bandwidth_usage	(	time_t	now,
		or_state_t *	state
	)

Save all our bandwidth tracking information to disk. Return 0 on success, -1 on failure.

Definition at line 705 of file hibernate.c.

Referenced by accounting_run_housekeeping(), and tor_cleanup().

◆ accounting_run_housekeeping()

void accounting_run_housekeeping ( time_t now )

Invoked once per second. Checks whether it is time to hibernate, record bandwidth used, etc.

Definition at line 585 of file hibernate.c.

Referenced by second_elapsed_callback(), and wakeup_event_callback().

◆ accounting_set_wakeup_time()

static void accounting_set_wakeup_time ( void )

static

Based on our interval and our estimated bandwidth, choose a deterministic (but random-ish) time to wake up.

Definition at line 600 of file hibernate.c.

◆ configure_accounting()

void configure_accounting ( time_t now )

Initialize the accounting subsystem.

Definition at line 430 of file hibernate.c.

Referenced by accounting_run_housekeeping().

◆ consider_hibernation()

void consider_hibernation ( time_t now )

Consider our environment and decide if it's time to start/stop hibernating.

Definition at line 1098 of file hibernate.c.

Referenced by second_elapsed_callback(), and wakeup_event_callback().

◆ edge_of_accounting_period_containing()

static time_t edge_of_accounting_period_containing	(	time_t	now,
		int	get_end
	)

static

If get_end, return the end of the accounting period that contains the time now. Else, return the start of the accounting period that contains the time now

Definition at line 344 of file hibernate.c.

Referenced by length_of_accounting_period_containing(), start_of_accounting_period_after(), and start_of_accounting_period_containing().

◆ get_accounting_bytes()

uint64_t get_accounting_bytes ( void )

Return the relevant number of bytes sent/received this interval based on the set AccountingRule

Definition at line 478 of file hibernate.c.

Referenced by hibernate_hard_limit_reached().

◆ getinfo_helper_accounting()

int getinfo_helper_accounting	(	control_connection_t *	conn,
		const char *	question,
		char **	answer,
		const char **	errmsg
	)

Helper function: called when we get a GETINFO request for an accounting-related key on the control connection conn. If we can answer the request for question, then set *answer to a newly allocated string holding the result. Otherwise, set *answer to NULL.

Definition at line 1170 of file hibernate.c.

◆ hibernate_begin()

static void hibernate_begin	(	hibernate_state_t	new_state,
		time_t	now
	)

static

Called when we get a SIGINT, or when bandwidth soft limit is reached. Puts us into "loose hibernation": we don't accept new connections, but we continue handling old ones.

Definition at line 840 of file hibernate.c.

Referenced by hibernate_begin_shutdown(), and hibernate_go_dormant().

◆ hibernate_begin_shutdown()

void hibernate_begin_shutdown ( void )

A wrapper around hibernate_begin, for when we get SIGINT.

Definition at line 927 of file hibernate.c.

◆ hibernate_end()

static void hibernate_end ( hibernate_state_t new_state )

static

Called when we've been hibernating and our timeout is reached.

Definition at line 910 of file hibernate.c.

◆ hibernate_end_time_elapsed()

static void hibernate_end_time_elapsed ( time_t now )

static

Called when hibernate_end_time has arrived.

Definition at line 1065 of file hibernate.c.

◆ hibernate_go_dormant()

static void hibernate_go_dormant ( time_t now )

static

If we aren't currently dormant, close all connections and become dormant.

Definition at line 955 of file hibernate.c.

◆ hibernate_hard_limit_reached()

static int hibernate_hard_limit_reached ( void )

static

Return true iff we have sent/received all the bytes we are willing to send/receive this interval.

Definition at line 797 of file hibernate.c.

◆ hibernate_schedule_wakeup_event()

static void hibernate_schedule_wakeup_event	(	time_t	now,
		time_t	end_time
	)

static

Schedule a mainloop event at end_time to wake up from a dormant state. We can't rely on this happening from second_elapsed_callback, since second_elapsed_callback will be shut down when we're dormant.

(Note that We might immediately go back to sleep after we set the next wakeup time.)

Definition at line 1017 of file hibernate.c.

Referenced by wakeup_event_callback().

◆ hibernate_soft_limit_reached()

static int hibernate_soft_limit_reached ( void )

static

Return true iff we have sent/received almost all the bytes we are willing to send/receive this interval.

Definition at line 808 of file hibernate.c.

◆ hibernate_state_to_string()

static const char * hibernate_state_to_string ( hibernate_state_t state )

static

Return the human-readable name for the hibernation state state

Definition at line 165 of file hibernate.c.

Referenced by on_hibernate_state_change().

◆ length_of_accounting_period_containing()

static long length_of_accounting_period_containing ( time_t now )

static

Return the length of the accounting period containing the time now.

Definition at line 422 of file hibernate.c.

◆ on_hibernate_state_change()

static void on_hibernate_state_change ( hibernate_state_t prev_state )

static

Helper function: called when the hibernation state changes, and sends a SERVER_STATUS event to notify interested controllers of the accounting state change.

Definition at line 1236 of file hibernate.c.

◆ read_bandwidth_usage()

static int read_bandwidth_usage ( void )

static

Read stored accounting information from disk. Return 0 on success; return -1 and change nothing on failure.

Definition at line 729 of file hibernate.c.

Referenced by configure_accounting().

◆ reset_accounting()

static void reset_accounting ( time_t now )

static

Called at the start of a new accounting interval: reset our expected bandwidth usage based on what happened last time, set up the start and end of the interval, and clear byte/time totals.

Definition at line 544 of file hibernate.c.

◆ start_of_accounting_period_after()

static time_t start_of_accounting_period_after ( time_t now )

static

Return the start of the accounting period that comes after the one containing the time now.

Definition at line 414 of file hibernate.c.

◆ start_of_accounting_period_containing()

static time_t start_of_accounting_period_containing ( time_t now )

static

Return the start of the accounting period containing the time now.

Definition at line 406 of file hibernate.c.

Referenced by configure_accounting().

◆ time_to_record_bandwidth_usage()

static int time_to_record_bandwidth_usage ( time_t now )

inlinestatic

Return true iff we should save our bandwidth usage to disk.

Definition at line 560 of file hibernate.c.

Referenced by accounting_run_housekeeping().

◆ update_expected_bandwidth()

static void update_expected_bandwidth ( void )

static

Set expected_bandwidth_usage based on how much we sent/received per minute last interval (if we were up for at least 30 minutes), or based on our declared bandwidth otherwise.

Definition at line 494 of file hibernate.c.

◆ wakeup_event_callback()

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

static

Called at the end of the interval, or at the wakeup time of the current interval, to exit the dormant state.

Definition at line 1041 of file hibernate.c.

Referenced by hibernate_schedule_wakeup_event().

◆ we_are_fully_hibernating()

int we_are_fully_hibernating ( void )

Return true iff we are currently fully hibernating – that is, if we are in a state where we expect to handle no network activity at all.

Definition at line 947 of file hibernate.c.

Referenced by net_is_completely_disabled().

◆ we_are_hibernating()

int we_are_hibernating ( void )

Return true iff we are currently hibernating – that is, if we are in any non-live state.

Definition at line 937 of file hibernate.c.

Referenced by check_descriptor_bandwidth_changed(), log_heartbeat(), net_is_disabled(), and router_build_fresh_unsigned_routerinfo().

Variable Documentation

◆ cfg_start_day

int cfg_start_day = 0

static

How many days,hours,minutes into each unit does our accounting interval start?

Definition at line 146 of file hibernate.c.

◆ cfg_unit

time_unit_t cfg_unit = UNIT_MONTH

static

What unit are we using for our accounting?

Definition at line 141 of file hibernate.c.

◆ expected_bandwidth_usage

uint64_t expected_bandwidth_usage = 0

static

How much bandwidth do we 'expect' to use per minute? (0 if we have no info from the last period.)

Definition at line 139 of file hibernate.c.

◆ hibernate_end_time

time_t hibernate_end_time = 0

static

If are hibernating, when do we plan to wake up? Set to 0 if we aren't hibernating.

Definition at line 69 of file hibernate.c.

Referenced by wakeup_event_callback().

◆ hibernate_state

hibernate_state_t hibernate_state = HIBERNATE_STATE_INITIAL

static

Are we currently awake, asleep, running out of bandwidth, or shutting down?

Definition at line 66 of file hibernate.c.

Referenced by hibernate_begin(), hibernate_end(), hibernate_go_dormant(), on_hibernate_state_change(), wakeup_event_callback(), we_are_fully_hibernating(), and we_are_hibernating().

◆ interval_end_time

time_t interval_end_time = 0

static

When will this accounting interval end?

Definition at line 134 of file hibernate.c.

Referenced by accounting_get_end_time(), accounting_get_interval_length(), accounting_run_housekeeping(), and wakeup_event_callback().

◆ interval_start_time

time_t interval_start_time = 0

static

When did this accounting interval start?

Definition at line 132 of file hibernate.c.

Referenced by accounting_get_interval_length(), accounting_record_bandwidth_usage(), configure_accounting(), and update_expected_bandwidth().

◆ interval_wakeup_time

time_t interval_wakeup_time = 0

static

How far into the accounting interval should we hibernate?

Definition at line 136 of file hibernate.c.

Referenced by wakeup_event_callback().

◆ n_bytes_at_soft_limit

uint64_t n_bytes_at_soft_limit = 0

static

How many bytes had we read/written when we hit the soft limit?

Definition at line 130 of file hibernate.c.

Referenced by update_expected_bandwidth().

◆ n_bytes_read_in_interval

uint64_t n_bytes_read_in_interval = 0

static

How many bytes have we read in this accounting interval?

Definition at line 119 of file hibernate.c.

Referenced by accounting_add_bytes(), and get_accounting_bytes().

◆ n_bytes_written_in_interval

uint64_t n_bytes_written_in_interval = 0

static

How many bytes have we written in this accounting interval?

Definition at line 121 of file hibernate.c.

Referenced by accounting_add_bytes(), and get_accounting_bytes().

◆ n_seconds_active_in_interval

uint32_t n_seconds_active_in_interval = 0

static

How many seconds have we been running this interval?

Definition at line 123 of file hibernate.c.

Referenced by accounting_add_bytes().

◆ n_seconds_to_hit_soft_limit

int n_seconds_to_hit_soft_limit = 0

static

How many seconds were we active in this interval before we hit our soft limit?

Definition at line 126 of file hibernate.c.

◆ shutdown_time

time_t shutdown_time = 0

static

If we are shutting down, when do we plan to finally exit? Set to 0 if we aren't shutting down. (This is obsolete; scheduled shutdowns are supposed to happen from mainloop_schedule_shutdown() now.)

Definition at line 73 of file hibernate.c.

◆ soft_limit_hit_at

time_t soft_limit_hit_at = 0

static

When in this interval was the soft limit hit.

Definition at line 128 of file hibernate.c.

Referenced by update_expected_bandwidth().

◆ wakeup_event

mainloop_event_t* wakeup_event = NULL

static

A timed event that we'll use when it's time to wake up from hibernation.

Definition at line 77 of file hibernate.c.

Referenced by hibernate_schedule_wakeup_event().

Macros

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ time_unit_t

Function Documentation

◆ accounting_add_bytes()

◆ accounting_free_all()

◆ accounting_get_end_time()

◆ accounting_get_interval_length()

◆ accounting_is_enabled()

◆ accounting_parse_options()

◆ accounting_record_bandwidth_usage()

◆ accounting_run_housekeeping()

◆ accounting_set_wakeup_time()

◆ configure_accounting()

◆ consider_hibernation()

◆ edge_of_accounting_period_containing()

◆ get_accounting_bytes()

◆ getinfo_helper_accounting()

◆ hibernate_begin()

◆ hibernate_begin_shutdown()

◆ hibernate_end()

◆ hibernate_end_time_elapsed()

◆ hibernate_go_dormant()

◆ hibernate_hard_limit_reached()

◆ hibernate_schedule_wakeup_event()

◆ hibernate_soft_limit_reached()

◆ hibernate_state_to_string()

◆ length_of_accounting_period_containing()

◆ on_hibernate_state_change()

◆ read_bandwidth_usage()

◆ reset_accounting()

◆ start_of_accounting_period_after()

◆ start_of_accounting_period_containing()

◆ time_to_record_bandwidth_usage()

◆ update_expected_bandwidth()

◆ wakeup_event_callback()

◆ we_are_fully_hibernating()

◆ we_are_hibernating()

Variable Documentation

◆ cfg_start_day

◆ cfg_unit

◆ expected_bandwidth_usage

◆ hibernate_end_time

◆ hibernate_state

◆ interval_end_time

◆ interval_start_time

◆ interval_wakeup_time

◆ n_bytes_at_soft_limit

◆ n_bytes_read_in_interval

◆ n_bytes_written_in_interval

◆ n_seconds_active_in_interval

◆ n_seconds_to_hit_soft_limit

◆ shutdown_time

◆ soft_limit_hit_at

◆ wakeup_event