Tor  0.4.7.0-alpha-dev
download_status_st.h
Go to the documentation of this file.
1 /* Copyright (c) 2001 Matej Pfajfar.
2  * Copyright (c) 2001-2004, Roger Dingledine.
3  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
4  * Copyright (c) 2007-2021, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
6 
7 /**
8  * @file download_status_st.h
9  * @brief Directory download status/schedule structure.
10  **/
11 
12 #ifndef DOWNLOAD_STATUS_ST_H
13 #define DOWNLOAD_STATUS_ST_H
14 
15 /** Information about our plans for retrying downloads for a downloadable
16  * directory object.
17  * Each type of downloadable directory object has a corresponding retry
18  * <b>schedule</b>, which can be different depending on whether the object is
19  * being downloaded from an authority or a mirror (<b>want_authority</b>).
20  * <b>next_attempt_at</b> contains the next time we will attempt to download
21  * the object.
22  * For schedules that <b>increment_on</b> failure, <b>n_download_failures</b>
23  * is used to determine the position in the schedule. (Each schedule is a
24  * smartlist of integer delays, parsed from a CSV option.) Every time a
25  * connection attempt fails, <b>n_download_failures</b> is incremented,
26  * the new delay value is looked up from the schedule, and
27  * <b>next_attempt_at</b> is set delay seconds from the time the previous
28  * connection failed. Therefore, at most one failure-based connection can be
29  * in progress for each download_status_t.
30  * For schedules that <b>increment_on</b> attempt, <b>n_download_attempts</b>
31  * is used to determine the position in the schedule. Every time a
32  * connection attempt is made, <b>n_download_attempts</b> is incremented,
33  * the new delay value is looked up from the schedule, and
34  * <b>next_attempt_at</b> is set delay seconds from the time the previous
35  * connection was attempted. Therefore, multiple concurrent attempted-based
36  * connections can be in progress for each download_status_t.
37  * After an object is successfully downloaded, any other concurrent connections
38  * are terminated. A new schedule which starts at position 0 is used for
39  * subsequent downloads of the same object.
40  */
42  time_t next_attempt_at; /**< When should we try downloading this object
43  * again? */
44  uint8_t n_download_failures; /**< Number of failed downloads of the most
45  * recent object, since the last success. */
46  uint8_t n_download_attempts; /**< Number of (potentially concurrent) attempts
47  * to download the most recent object, since
48  * the last success. */
49  download_schedule_bitfield_t schedule : 8; /**< What kind of object is being
50  * downloaded? This determines the
51  * schedule used for the download.
52  */
53  download_want_authority_bitfield_t want_authority : 1; /**< Is the download
54  * happening from an authority
55  * or a mirror? This determines
56  * the schedule used for the
57  * download. */
58  download_schedule_increment_bitfield_t increment_on : 1; /**< does this
59  * schedule increment on each attempt,
60  * or after each failure? */
61  uint8_t last_backoff_position; /**< number of attempts/failures, depending
62  * on increment_on, when we last recalculated
63  * the delay. Only updated if backoff
64  * == 1. */
65  int last_delay_used; /**< last delay used for random exponential backoff;
66  * only updated if backoff == 1 */
67 };
68 
69 #endif /* !defined(DOWNLOAD_STATUS_ST_H) */
download_want_authority_bitfield_t want_authority
download_schedule_increment_bitfield_t increment_on
download_schedule_bitfield_t schedule