download_status_st.h (3881B)
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 */ 41 struct download_status_t { 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) */