circuitlist.h File Reference

Header file for circuitlist.c. More...

#include "testsupport.h"
#include "hs_ident.h"

Include dependency graph for circuitlist.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	circuit_mark_for_close(c, reason)   circuit_mark_for_close_((c), (reason), __LINE__, SHORT_FILE__)

Functions
	MOCK_DECL (smartlist_t *, circuit_get_global_list,(void))
smartlist_t *	circuit_get_global_origin_circuit_list (void)
int	circuit_any_opened_circuits (void)
int	circuit_any_opened_circuits_cached (void)
void	circuit_cache_opened_circuit_state (int circuits_are_opened)
const char *	circuit_state_to_string (int state)
const char *	circuit_purpose_to_controller_string (uint8_t purpose)
const char *	circuit_purpose_to_controller_hs_state_string (uint8_t purpose)
const char *	circuit_purpose_to_string (uint8_t purpose)
void	circuit_dump_by_conn (connection_t *conn, int severity)
void	circuit_set_p_circid_chan (or_circuit_t *circ, circid_t id, channel_t *chan)
void	circuit_set_n_circid_chan (circuit_t *circ, circid_t id, channel_t *chan)
void	channel_mark_circid_unusable (channel_t *chan, circid_t id)
void	channel_mark_circid_usable (channel_t *chan, circid_t id)
time_t	circuit_id_when_marked_unusable_on_channel (circid_t circ_id, channel_t *chan)
void	circuit_set_state (circuit_t *circ, uint8_t state)
void	circuit_close_all_marked (void)
int32_t	circuit_initial_package_window (void)
origin_circuit_t *	origin_circuit_new (void)
or_circuit_t *	or_circuit_new (circid_t p_circ_id, channel_t *p_chan)
circuit_t *	circuit_get_by_circid_channel (circid_t circ_id, channel_t *chan)
circuit_t *	circuit_get_by_circid_channel_even_if_marked (circid_t circ_id, channel_t *chan)
int	circuit_id_in_use_on_channel (circid_t circ_id, channel_t *chan)
circuit_t *	circuit_get_by_edge_conn (edge_connection_t *conn)
void	circuit_unlink_all_from_channel (channel_t *chan, int reason)
origin_circuit_t *	circuit_get_by_global_id (uint32_t id)
origin_circuit_t *	circuit_get_ready_rend_circ_by_rend_data (const rend_data_t *rend_data)
origin_circuit_t *	circuit_get_next_by_pk_and_purpose (origin_circuit_t *start, const uint8_t *digest, uint8_t purpose)
origin_circuit_t *	circuit_get_next_service_intro_circ (origin_circuit_t *start)
origin_circuit_t *	circuit_get_next_service_rp_circ (origin_circuit_t *start)
origin_circuit_t *	circuit_get_next_service_hsdir_circ (origin_circuit_t *start)
origin_circuit_t *	circuit_find_to_cannibalize (uint8_t purpose, extend_info_t *info, int flags)
void	circuit_mark_all_unused_circs (void)
void	circuit_mark_all_dirty_circs_as_unusable (void)
	MOCK_DECL (void, circuit_mark_for_close_,(circuit_t *circ, int reason, int line, const char *file))
int	circuit_get_cpath_len (origin_circuit_t *circ)
int	circuit_get_cpath_opened_len (const origin_circuit_t *)
void	circuit_clear_cpath (origin_circuit_t *circ)
crypt_path_t *	circuit_get_cpath_hop (origin_circuit_t *circ, int hopnum)
void	circuit_get_all_pending_on_channel (smartlist_t *out, channel_t *chan)
int	circuit_count_pending_on_channel (channel_t *chan)
void	assert_cpath_layer_ok (const crypt_path_t *cp)
	MOCK_DECL (void, assert_circuit_ok,(const circuit_t *c))
void	circuit_free_all (void)
void	circuits_handle_oom (size_t current_allocation)
void	circuit_clear_testing_cell_stats (circuit_t *circ)
void	channel_note_destroy_pending (channel_t *chan, circid_t id)
	MOCK_DECL (void, channel_note_destroy_not_pending,(channel_t *chan, circid_t id))
smartlist_t *	circuit_find_circuits_to_upgrade_from_guard_wait (void)

Detailed Description

Header file for circuitlist.c.

Function Documentation

assert_cpath_layer_ok()

void assert_cpath_layer_ok

(

const crypt_path_t *

cp

)

Verify that cpath layer cp has all of its invariants correct. Trigger an assert if anything is invalid.

channel_mark_circid_unusable()

void channel_mark_circid_unusable	(	channel_t *	chan,
		circid_t	id
	)

Mark that circuit id id shouldn't be used on channel chan, even if there is no circuit on the channel. We use this to keep the circuit id from getting re-used while we have queued but not yet sent a destroy cell.

Here is the caller graph for this function:

channel_mark_circid_usable()

void channel_mark_circid_usable	(	channel_t *	chan,
		circid_t	id
	)

Mark that a circuit id id can be used again on chan. We use this to re-enable the circuit ID after we've sent a destroy cell.

Here is the caller graph for this function:

channel_note_destroy_pending()

void channel_note_destroy_pending	(	channel_t *	chan,
		circid_t	id
	)

Called to indicate that a DESTROY is pending on chan with circuit ID id, but hasn't been sent yet.

Here is the call graph for this function:

circuit_any_opened_circuits()

int circuit_any_opened_circuits

(

void

)

Return true if we have any opened general-purpose 3 hop origin circuits.

The result from this function is cached for use by circuit_any_opened_circuits_cached().

Here is the call graph for this function:

Here is the caller graph for this function:

circuit_any_opened_circuits_cached()

int circuit_any_opened_circuits_cached

(

void

)

Return true if there were any opened circuits since the last call to circuit_any_opened_circuits(), or since circuit_expire_building() last ran (it runs roughly once per second).

Here is the caller graph for this function:

circuit_cache_opened_circuit_state()

void circuit_cache_opened_circuit_state

(

int

circuits_are_opened

)

Cache the "any circuits opened" state, as specified in param circuits_are_opened. This is a helper function to update the circuit opened status whenever we happen to look at the circuit list.

Here is the caller graph for this function:

circuit_clear_cpath()

void circuit_clear_cpath

(

origin_circuit_t *

circ

)

Deallocate the linked list circ->cpath, and remove the cpath from circ.

circuit_clear_testing_cell_stats()

void circuit_clear_testing_cell_stats

(

circuit_t *

circ

)

Free all storage held in circ->testing_cell_stats

Here is the caller graph for this function:

circuit_close_all_marked()

void circuit_close_all_marked

(

void

)

Detach from the global circuit list, and deallocate, all circuits that have been marked for close.

Here is the call graph for this function:

circuit_count_pending_on_channel()

int circuit_count_pending_on_channel

(

channel_t *

chan

)

Return the number of circuits in state CHAN_WAIT, waiting for the given channel.

Here is the call graph for this function:

circuit_dump_by_conn()

void circuit_dump_by_conn	(	connection_t *	conn,
		int	severity
	)

Log, at severity severity, information about each circuit that is connected to conn.

circuit_find_circuits_to_upgrade_from_guard_wait()

smartlist_t* circuit_find_circuits_to_upgrade_from_guard_wait

(

void

)

Check whether any of the origin circuits that are waiting to see if their guard is good enough to use can be upgraded to "ready". If so, return a new smartlist containing them. Otherwise return NULL.

Here is the call graph for this function:

Here is the caller graph for this function:

circuit_find_to_cannibalize()

origin_circuit_t* circuit_find_to_cannibalize	(	uint8_t	purpose_to_produce,
		extend_info_t *	info,
		int	flags
	)

Return a circuit that is open, is CIRCUIT_PURPOSE_C_GENERAL, has a timestamp_dirty value of 0, has flags matching the CIRCLAUNCH_* flags in flags, and if info is defined, does not already use info as any of its hops; or NULL if no circuit fits this description.

The purpose argument refers to the purpose of the circuit we want to create, not the purpose of the circuit we want to cannibalize.

If !CIRCLAUNCH_NEED_UPTIME, prefer returning non-uptime circuits.

To "cannibalize" a circuit means to extend it an extra hop, and use it for some other purpose than we had originally intended. We do this when we want to perform some low-bandwidth task at a specific relay, and we would like the circuit to complete as soon as possible. (If we were going to use a lot of bandwidth, we wouldn't want a circuit with an extra hop. If we didn't care about circuit completion latency, we would just build a new circuit.)

circuit_free_all()

void circuit_free_all

(

void

)

Release all storage held by circuits.

circuit_get_all_pending_on_channel()

void circuit_get_all_pending_on_channel	(	smartlist_t *	out,
		channel_t *	chan
	)

Append to out all circuits in state CHAN_WAIT waiting for the given connection.

Here is the call graph for this function:

Here is the caller graph for this function:

circuit_get_by_circid_channel()

circuit_t* circuit_get_by_circid_channel	(	circid_t	circ_id,
		channel_t *	chan
	)

Return a circ such that:

• circ->n_circ_id or circ->p_circ_id is equal to circ_id, and
• circ is attached to chan, either as p_chan or n_chan.
• circ is not marked for close. Return NULL if no such circuit exists.

circuit_get_by_circid_channel_even_if_marked()

circuit_t* circuit_get_by_circid_channel_even_if_marked	(	circid_t	circ_id,
		channel_t *	chan
	)

Return a circ such that:

• circ->n_circ_id or circ->p_circ_id is equal to circ_id, and
• circ is attached to chan, either as p_chan or n_chan. Return NULL if no such circuit exists.

Here is the caller graph for this function:

circuit_get_by_edge_conn()

circuit_t* circuit_get_by_edge_conn

(

edge_connection_t *

conn

)

Return the circuit that a given edge connection is using.

Here is the caller graph for this function:

circuit_get_by_global_id()

origin_circuit_t* circuit_get_by_global_id

(

uint32_t

id

)

Return the circuit whose global ID is id, or NULL if no such circuit exists.

circuit_get_cpath_hop()

crypt_path_t* circuit_get_cpath_hop	(	origin_circuit_t *	circ,
		int	hopnum
	)

Return the hopnumth hop in circ->cpath, or NULL if there aren't that many hops in the list. hopnum starts at 1. Returns NULL if hopnum is 0 or negative.

circuit_get_cpath_len()

int circuit_get_cpath_len

(

origin_circuit_t *

circ

)

Return the number of hops in circuit's path. If circ has no entries, or is NULL, returns 0.

Here is the caller graph for this function:

circuit_get_cpath_opened_len()

int circuit_get_cpath_opened_len

(

const origin_circuit_t *

circ

)

Return the number of opened hops in circuit's path. If circ has no entries, or is NULL, returns 0.

Here is the caller graph for this function:

circuit_get_global_origin_circuit_list()

smartlist_t* circuit_get_global_origin_circuit_list

(

void

)

Return a pointer to the global list of origin circuits.

Here is the caller graph for this function:

circuit_get_next_by_pk_and_purpose()

origin_circuit_t* circuit_get_next_by_pk_and_purpose	(	origin_circuit_t *	start,
		const uint8_t *	digest,
		uint8_t	purpose
	)

Return the first circuit originating here in global_circuitlist after start whose purpose is purpose, and where digest (if set) matches the private key digest of the rend data associated with the circuit. Return NULL if no circuit is found. If start is NULL, begin at the start of the list.

circuit_get_next_service_intro_circ()

origin_circuit_t* circuit_get_next_service_intro_circ

(

origin_circuit_t *

start

)

Return the first service introduction circuit originating from the global circuit list after start or at the start of the list if start is NULL. Return NULL if no circuit is found.

A service introduction point circuit has a purpose of either CIRCUIT_PURPOSE_S_ESTABLISH_INTRO or CIRCUIT_PURPOSE_S_INTRO. This does not return a circuit marked for close and its state must be open.

circuit_get_next_service_rp_circ()

origin_circuit_t* circuit_get_next_service_rp_circ

(

origin_circuit_t *

start

)

Return the first service rendezvous circuit originating from the global circuit list after start or at the start of the list if start is NULL. Return NULL if no circuit is found.

A service rendezvous point circuit has a purpose of either CIRCUIT_PURPOSE_S_CONNECT_REND or CIRCUIT_PURPOSE_S_REND_JOINED. This does not return a circuit marked for close and its state must be open.

circuit_get_ready_rend_circ_by_rend_data()

origin_circuit_t* circuit_get_ready_rend_circ_by_rend_data

(

const rend_data_t *

rend_data

)

Return a circ such that

• circ->rend_data->onion_address is equal to rend_data->onion_address,
• circ->rend_data->rend_cookie is equal to rend_data->rend_cookie, and
• circ->purpose is equal to CIRCUIT_PURPOSE_C_REND_READY.

Return NULL if no such circuit exists.

circuit_id_in_use_on_channel()

int circuit_id_in_use_on_channel	(	circid_t	circ_id,
		channel_t *	chan
	)

Return true iff the circuit ID circ_id is currently used by a circuit, marked or not, on chan, or if the circ ID is reserved until a queued destroy cell can be sent.

(Return 1 if the circuit is present, marked or not; Return 2 if the circuit ID is pending a destroy.)

circuit_id_when_marked_unusable_on_channel()

time_t circuit_id_when_marked_unusable_on_channel	(	circid_t	circ_id,
		channel_t *	chan
	)

Helper for debugging 12184. Returns the time since which 'circ_id' has been marked unusable on 'chan'.

circuit_initial_package_window()

int32_t circuit_initial_package_window

(

void

)

Pick a reasonable package_window to start out for our circuits. Originally this was hard-coded at 1000, but now the consensus votes on the answer. See proposal 168.

circuit_mark_all_dirty_circs_as_unusable()

void circuit_mark_all_dirty_circs_as_unusable

(

void

)

Go through the circuitlist; for each circuit that starts at us and is dirty, frob its timestamp_dirty so we won't use it for any new streams.

This is useful for letting the user change pseudonyms, so new streams will not be linkable to old streams.

Here is the call graph for this function:

Here is the caller graph for this function:

circuit_mark_all_unused_circs()

void circuit_mark_all_unused_circs

(

void

)

Go through the circuitlist; mark-for-close each circuit that starts at us but has not yet been used.

Here is the caller graph for this function:

circuit_purpose_to_controller_hs_state_string()

const char* circuit_purpose_to_controller_hs_state_string

(

uint8_t

purpose

)

Return a string specifying the state of the hidden-service circuit purpose purpose, or NULL if purpose is not a hidden-service-related circuit purpose.

circuit_purpose_to_controller_string()

const char* circuit_purpose_to_controller_string

(

uint8_t

purpose

)

Map a circuit purpose to a string suitable to be displayed to a controller.

Here is the call graph for this function:

circuit_purpose_to_string()

const char* circuit_purpose_to_string

(

uint8_t

purpose

)

Return a human-readable string for the circuit purpose purpose.

Here is the call graph for this function:

Here is the caller graph for this function:

circuit_set_n_circid_chan()

void circuit_set_n_circid_chan	(	circuit_t *	circ,
		circid_t	id,
		channel_t *	chan
	)

Set the n_conn field of a circuit circ, along with the corresponding circuit ID, and add the circuit as appropriate to the (chan,id)->circuit map.

Here is the call graph for this function:

circuit_set_p_circid_chan()

void circuit_set_p_circid_chan	(	or_circuit_t *	or_circ,
		circid_t	id,
		channel_t *	chan
	)

Set the p_conn field of a circuit circ, along with the corresponding circuit ID, and add the circuit as appropriate to the (chan,id)->circuit map.

Here is the call graph for this function:

circuit_set_state()

void circuit_set_state	(	circuit_t *	circ,
		uint8_t	state
	)

Change the state of circ to state, adding it to or removing it from lists as appropriate.

Here is the call graph for this function:

Here is the caller graph for this function:

circuit_state_to_string()

const char* circuit_state_to_string

(

int

state

)

Function to make circ->state human-readable

circuit_unlink_all_from_channel()

void circuit_unlink_all_from_channel	(	channel_t *	chan,
		int	reason
	)

For each circuit that has chan as n_chan or p_chan, unlink the circuit from the chan,circid map, and mark it for close if it hasn't been marked already.

Here is the call graph for this function:

circuits_handle_oom()

void circuits_handle_oom

(

size_t

current_allocation

)

We're out of memory for cells, having allocated current_allocation bytes' worth. Kill the 'worst' circuits until we're under FRACTION_OF_DATA_TO_RETAIN_ON_OOM of our maximum usage.

or_circuit_new()

or_circuit_t* or_circuit_new	(	circid_t	p_circ_id,
		channel_t *	p_chan
	)

Allocate a new or_circuit_t, connected to p_chan as p_circ_id. If p_chan is NULL, the circuit is unattached.

origin_circuit_new()

origin_circuit_t* origin_circuit_new

(

void

)

Allocate space for a new circuit, initializing with p_circ_id and p_conn. Add it to the global circuit list.

Here is the caller graph for this function: