]>
Commit | Line | Data |
---|---|---|
0118833a AL |
1 | // -*- mode: cpp; mode: fold -*- |
2 | // Description /*{{{*/ | |
b3d44315 | 3 | // $Id: acquire.h,v 1.29.2.1 2003/12/24 23:09:17 mdz Exp $ |
0118833a AL |
4 | /* ###################################################################### |
5 | ||
6 | Acquire - File Acquiration | |
7 | ||
8 | This module contians the Acquire system. It is responsible for bringing | |
9 | files into the local pathname space. It deals with URIs for files and | |
10 | URI handlers responsible for downloading or finding the URIs. | |
11 | ||
12 | Each file to download is represented by an Acquire::Item class subclassed | |
13 | into a specialization. The Item class can add itself to several URI | |
14 | acquire queues each prioritized by the download scheduler. When the | |
15 | system is run the proper URI handlers are spawned and the the acquire | |
16 | queues are fed into the handlers by the schedular until the queues are | |
17 | empty. This allows for an Item to be downloaded from an alternate source | |
18 | if the first try turns out to fail. It also alows concurrent downloading | |
19 | of multiple items from multiple sources as well as dynamic balancing | |
20 | of load between the sources. | |
21 | ||
22 | Schedualing of downloads is done on a first ask first get basis. This | |
23 | preserves the order of the download as much as possible. And means the | |
24 | fastest source will tend to process the largest number of files. | |
25 | ||
26 | Internal methods and queues for performing gzip decompression, | |
27 | md5sum hashing and file copying are provided to allow items to apply | |
28 | a number of transformations to the data files they are working with. | |
29 | ||
30 | ##################################################################### */ | |
31 | /*}}}*/ | |
3174e150 | 32 | |
92fcbfc1 | 33 | /** \defgroup acquire Acquire system {{{ |
3174e150 MV |
34 | * |
35 | * \brief The Acquire system is responsible for retrieving files from | |
36 | * local or remote URIs and postprocessing them (for instance, | |
37 | * verifying their authenticity). The core class in this system is | |
38 | * pkgAcquire, which is responsible for managing the download queues | |
39 | * during the download. There is at least one download queue for | |
40 | * each supported protocol; protocols such as http may provide one | |
41 | * queue per host. | |
42 | * | |
43 | * Each file to download is represented by a subclass of | |
44 | * pkgAcquire::Item. The files add themselves to the download | |
45 | * queue(s) by providing their URI information to | |
46 | * pkgAcquire::Item::QueueURI, which calls pkgAcquire::Enqueue. | |
47 | * | |
48 | * Once the system is set up, the Run method will spawn subprocesses | |
49 | * to handle the enqueued URIs; the scheduler will then take items | |
50 | * from the queues and feed them into the handlers until the queues | |
51 | * are empty. | |
52 | * | |
53 | * \todo Acquire supports inserting an object into several queues at | |
54 | * once, but it is not clear what its behavior in this case is, and | |
55 | * no subclass of pkgAcquire::Item seems to actually use this | |
56 | * capability. | |
92fcbfc1 | 57 | */ /*}}}*/ |
3174e150 MV |
58 | |
59 | /** \addtogroup acquire | |
60 | * | |
61 | * @{ | |
62 | * | |
63 | * \file acquire.h | |
64 | */ | |
65 | ||
0118833a AL |
66 | #ifndef PKGLIB_ACQUIRE_H |
67 | #define PKGLIB_ACQUIRE_H | |
68 | ||
1cd1c398 | 69 | #include <apt-pkg/macros.h> |
229fb1a3 | 70 | #include <apt-pkg/weakptr.h> |
1cd1c398 | 71 | |
0118833a AL |
72 | #include <vector> |
73 | #include <string> | |
74 | ||
453b82a3 | 75 | #include <stddef.h> |
b98f2859 | 76 | #include <sys/time.h> |
453b82a3 DK |
77 | #include <sys/select.h> |
78 | ||
79 | #ifndef APT_10_CLEANER_HEADERS | |
0a8a80e5 | 80 | #include <unistd.h> |
453b82a3 | 81 | #endif |
0a8a80e5 | 82 | |
a4f6bdc8 DK |
83 | #ifndef APT_8_CLEANER_HEADERS |
84 | using std::vector; | |
85 | using std::string; | |
86 | #endif | |
87 | ||
8267fe24 | 88 | class pkgAcquireStatus; |
3174e150 | 89 | |
92fcbfc1 | 90 | /** \brief The core download scheduler. {{{ |
3174e150 MV |
91 | * |
92 | * This class represents an ongoing download. It manages the lists | |
93 | * of active and pending downloads and handles setting up and tearing | |
94 | * down download-related structures. | |
95 | * | |
96 | * \todo Why all the protected data items and methods? | |
97 | */ | |
0118833a AL |
98 | class pkgAcquire |
99 | { | |
e92e897a MV |
100 | private: |
101 | /** \brief FD of the Lock file we acquire in Setup (if any) */ | |
102 | int LockFD; | |
103 | /** \brief dpointer placeholder (for later in case we need it) */ | |
104 | void *d; | |
105 | ||
0118833a AL |
106 | public: |
107 | ||
108 | class Item; | |
109 | class Queue; | |
110 | class Worker; | |
111 | struct MethodConfig; | |
8267fe24 | 112 | struct ItemDesc; |
b2e465d6 AL |
113 | friend class Item; |
114 | friend class Queue; | |
b4fc9b6f | 115 | |
8f3ba4e8 DK |
116 | typedef std::vector<Item *>::iterator ItemIterator; |
117 | typedef std::vector<Item *>::const_iterator ItemCIterator; | |
3174e150 | 118 | |
0118833a AL |
119 | protected: |
120 | ||
3174e150 MV |
121 | /** \brief A list of items to download. |
122 | * | |
123 | * This is built monotonically as items are created and only | |
124 | * emptied when the download shuts down. | |
125 | */ | |
8f3ba4e8 | 126 | std::vector<Item *> Items; |
0a8a80e5 | 127 | |
3174e150 MV |
128 | /** \brief The head of the list of active queues. |
129 | * | |
130 | * \todo why a hand-managed list of queues instead of std::list or | |
131 | * std::set? | |
132 | */ | |
0118833a | 133 | Queue *Queues; |
3174e150 MV |
134 | |
135 | /** \brief The head of the list of active workers. | |
136 | * | |
137 | * \todo why a hand-managed list of workers instead of std::list | |
138 | * or std::set? | |
139 | */ | |
0a8a80e5 | 140 | Worker *Workers; |
3174e150 MV |
141 | |
142 | /** \brief The head of the list of acquire method configurations. | |
143 | * | |
144 | * Each protocol (http, ftp, gzip, etc) via which files can be | |
145 | * fetched can have a representation in this list. The | |
146 | * configuration data is filled in by parsing the 100 Capabilities | |
147 | * string output by a method on startup (see | |
148 | * pkgAcqMethod::pkgAcqMethod and pkgAcquire::GetConfig). | |
149 | * | |
150 | * \todo why a hand-managed config dictionary instead of std::map? | |
151 | */ | |
0118833a | 152 | MethodConfig *Configs; |
3174e150 MV |
153 | |
154 | /** \brief The progress indicator for this download. */ | |
8267fe24 | 155 | pkgAcquireStatus *Log; |
3174e150 | 156 | |
73da43e9 | 157 | /** \brief The number of files which are to be fetched. */ |
0a8a80e5 | 158 | unsigned long ToFetch; |
8267fe24 | 159 | |
3174e150 MV |
160 | // Configurable parameters for the scheduler |
161 | ||
162 | /** \brief Represents the queuing strategy for remote URIs. */ | |
163 | enum QueueStrategy { | |
164 | /** \brief Generate one queue for each protocol/host combination; downloads from | |
165 | * multiple hosts can proceed in parallel. | |
166 | */ | |
167 | QueueHost, | |
168 | /** \brief Generate a single queue for each protocol; serialize | |
169 | * downloads from multiple hosts. | |
170 | */ | |
171 | QueueAccess} QueueMode; | |
172 | ||
173 | /** \brief If \b true, debugging information will be dumped to std::clog. */ | |
1cd1c398 | 174 | bool const Debug; |
3174e150 | 175 | /** \brief If \b true, a download is currently in progress. */ |
8b89e57f | 176 | bool Running; |
3174e150 MV |
177 | |
178 | /** \brief Add the given item to the list of items. */ | |
0118833a | 179 | void Add(Item *Item); |
3174e150 MV |
180 | |
181 | /** \brief Remove the given item from the list of items. */ | |
0118833a | 182 | void Remove(Item *Item); |
3174e150 MV |
183 | |
184 | /** \brief Add the given worker to the list of workers. */ | |
0a8a80e5 | 185 | void Add(Worker *Work); |
3174e150 MV |
186 | |
187 | /** \brief Remove the given worker from the list of workers. */ | |
0a8a80e5 AL |
188 | void Remove(Worker *Work); |
189 | ||
3174e150 MV |
190 | /** \brief Insert the given fetch request into the appropriate queue. |
191 | * | |
192 | * \param Item The URI to download and the item to download it | |
193 | * for. Copied by value into the queue; no reference to Item is | |
194 | * retained. | |
195 | */ | |
8267fe24 | 196 | void Enqueue(ItemDesc &Item); |
3174e150 MV |
197 | |
198 | /** \brief Remove all fetch requests for this item from all queues. */ | |
0a8a80e5 | 199 | void Dequeue(Item *Item); |
3174e150 MV |
200 | |
201 | /** \brief Determine the fetch method and queue of a URI. | |
202 | * | |
203 | * \param URI The URI to fetch. | |
204 | * | |
205 | * \param[out] Config A location in which to place the method via | |
206 | * which the URI is to be fetched. | |
207 | * | |
208 | * \return the string-name of the queue in which a fetch request | |
209 | * for the given URI should be placed. | |
210 | */ | |
8f3ba4e8 | 211 | std::string QueueName(std::string URI,MethodConfig const *&Config); |
0a8a80e5 | 212 | |
3174e150 MV |
213 | /** \brief Build up the set of file descriptors upon which select() should |
214 | * block. | |
215 | * | |
216 | * The default implementation inserts the file descriptors | |
217 | * corresponding to active downloads. | |
218 | * | |
219 | * \param[out] Fd The largest file descriptor in the generated sets. | |
220 | * | |
221 | * \param[out] RSet The set of file descriptors that should be | |
222 | * watched for input. | |
223 | * | |
224 | * \param[out] WSet The set of file descriptors that should be | |
225 | * watched for output. | |
226 | */ | |
281daf46 | 227 | virtual void SetFds(int &Fd,fd_set *RSet,fd_set *WSet); |
3174e150 MV |
228 | |
229 | /** Handle input from and output to file descriptors which select() | |
230 | * has determined are ready. The default implementation | |
231 | * dispatches to all active downloads. | |
232 | * | |
233 | * \param RSet The set of file descriptors that are ready for | |
234 | * input. | |
235 | * | |
236 | * \param WSet The set of file descriptors that are ready for | |
237 | * output. | |
238 | */ | |
281daf46 | 239 | virtual void RunFds(fd_set *RSet,fd_set *WSet); |
93bf083d | 240 | |
3174e150 MV |
241 | /** \brief Check for idle queues with ready-to-fetch items. |
242 | * | |
243 | * Called by pkgAcquire::Queue::Done each time an item is dequeued | |
244 | * but remains on some queues; i.e., another queue should start | |
245 | * fetching it. | |
246 | */ | |
93bf083d | 247 | void Bump(); |
0118833a AL |
248 | |
249 | public: | |
3b5421b4 | 250 | |
3174e150 MV |
251 | /** \brief Retrieve information about a fetch method by name. |
252 | * | |
253 | * \param Access The name of the method to look up. | |
254 | * | |
255 | * \return the method whose name is Access, or \b NULL if no such method exists. | |
256 | */ | |
8f3ba4e8 | 257 | MethodConfig *GetConfig(std::string Access); |
024d1123 | 258 | |
3174e150 MV |
259 | /** \brief Provides information on how a download terminated. */ |
260 | enum RunResult { | |
261 | /** \brief All files were fetched successfully. */ | |
262 | Continue, | |
263 | ||
264 | /** \brief Some files failed to download. */ | |
265 | Failed, | |
266 | ||
267 | /** \brief The download was cancelled by the user (i.e., #Log's | |
268 | * pkgAcquireStatus::Pulse() method returned \b false). | |
269 | */ | |
270 | Cancelled}; | |
024d1123 | 271 | |
3174e150 MV |
272 | /** \brief Download all the items that have been Add()ed to this |
273 | * download process. | |
274 | * | |
275 | * This method will block until the download completes, invoking | |
276 | * methods on #Log to report on the progress of the download. | |
277 | * | |
278 | * \param PulseInterval The method pkgAcquireStatus::Pulse will be | |
279 | * invoked on #Log at intervals of PulseInterval milliseconds. | |
280 | * | |
281 | * \return the result of the download. | |
282 | */ | |
283 | RunResult Run(int PulseInterval=500000); | |
284 | ||
285 | /** \brief Remove all items from this download process, terminate | |
286 | * all download workers, and empty all queues. | |
287 | */ | |
281daf46 AL |
288 | void Shutdown(); |
289 | ||
255c9e4b | 290 | /** \brief Get the first Worker object. |
3174e150 MV |
291 | * |
292 | * \return the first active worker in this download process. | |
293 | */ | |
8267fe24 | 294 | inline Worker *WorkersBegin() {return Workers;}; |
3174e150 | 295 | |
255c9e4b | 296 | /** \brief Advance to the next Worker object. |
3174e150 MV |
297 | * |
298 | * \return the worker immediately following I, or \b NULL if none | |
299 | * exists. | |
300 | */ | |
a02db58f | 301 | Worker *WorkerStep(Worker *I) APT_PURE; |
3174e150 MV |
302 | |
303 | /** \brief Get the head of the list of items. */ | |
b4fc9b6f | 304 | inline ItemIterator ItemsBegin() {return Items.begin();}; |
3174e150 MV |
305 | |
306 | /** \brief Get the end iterator of the list of items. */ | |
b4fc9b6f | 307 | inline ItemIterator ItemsEnd() {return Items.end();}; |
f7a08e33 AL |
308 | |
309 | // Iterate over queued Item URIs | |
310 | class UriIterator; | |
3174e150 MV |
311 | /** \brief Get the head of the list of enqueued item URIs. |
312 | * | |
313 | * This iterator will step over every element of every active | |
314 | * queue. | |
315 | */ | |
f7a08e33 | 316 | UriIterator UriBegin(); |
3174e150 | 317 | /** \brief Get the end iterator of the list of enqueued item URIs. */ |
f7a08e33 AL |
318 | UriIterator UriEnd(); |
319 | ||
3174e150 MV |
320 | /** Deletes each entry in the given directory that is not being |
321 | * downloaded by this object. For instance, when downloading new | |
322 | * list files, calling Clean() will delete the old ones. | |
323 | * | |
324 | * \param Dir The directory to be cleaned out. | |
325 | * | |
326 | * \return \b true if the directory exists and is readable. | |
327 | */ | |
8f3ba4e8 | 328 | bool Clean(std::string Dir); |
a6568219 | 329 | |
3174e150 MV |
330 | /** \return the total size in bytes of all the items included in |
331 | * this download. | |
332 | */ | |
a3c4c81a | 333 | unsigned long long TotalNeeded(); |
3174e150 MV |
334 | |
335 | /** \return the size in bytes of all non-local items included in | |
336 | * this download. | |
337 | */ | |
a3c4c81a | 338 | unsigned long long FetchNeeded(); |
3174e150 MV |
339 | |
340 | /** \return the amount of data to be fetched that is already | |
341 | * present on the filesystem. | |
342 | */ | |
a3c4c81a | 343 | unsigned long long PartialPresent(); |
b3d44315 | 344 | |
1cd1c398 | 345 | /** \brief Delayed constructor |
3174e150 | 346 | * |
1cd1c398 DK |
347 | * \param Progress indicator associated with this download or |
348 | * \b NULL for none. This object is not owned by the | |
3174e150 MV |
349 | * download process and will not be deleted when the pkgAcquire |
350 | * object is destroyed. Naturally, it should live for at least as | |
351 | * long as the pkgAcquire object does. | |
1cd1c398 DK |
352 | * \param Lock defines a lock file that should be acquired to ensure |
353 | * only one Acquire class is in action at the time or an empty string | |
04a54261 DK |
354 | * if no lock file should be used. If set also all needed directories |
355 | * will be created. | |
3174e150 | 356 | */ |
04a54261 | 357 | APT_DEPRECATED bool Setup(pkgAcquireStatus *Progress = NULL, std::string const &Lock = ""); |
1cd1c398 | 358 | |
4a53151a DK |
359 | void SetLog(pkgAcquireStatus *Progress) { Log = Progress; } |
360 | ||
04a54261 DK |
361 | /** \brief acquire lock and perform directory setup |
362 | * | |
363 | * \param Lock defines a lock file that should be acquired to ensure | |
364 | * only one Acquire class is in action at the time or an empty string | |
365 | * if no lock file should be used. If set also all needed directories | |
366 | * will be created and setup. | |
367 | */ | |
368 | bool GetLock(std::string const &Lock); | |
369 | ||
1cd1c398 | 370 | /** \brief Construct a new pkgAcquire. */ |
04a54261 | 371 | pkgAcquire(pkgAcquireStatus *Log); |
1cd1c398 | 372 | pkgAcquire(); |
3174e150 MV |
373 | |
374 | /** \brief Destroy this pkgAcquire object. | |
375 | * | |
376 | * Destroys all queue, method, and item objects associated with | |
377 | * this download. | |
378 | */ | |
58d63ae6 | 379 | virtual ~pkgAcquire(); |
1cd1c398 | 380 | |
0118833a AL |
381 | }; |
382 | ||
3174e150 MV |
383 | /** \brief Represents a single download source from which an item |
384 | * should be downloaded. | |
385 | * | |
386 | * An item may have several assocated ItemDescs over its lifetime. | |
387 | */ | |
229fb1a3 | 388 | struct pkgAcquire::ItemDesc : public WeakPointable |
8267fe24 | 389 | { |
3174e150 | 390 | /** \brief The URI from which to download this item. */ |
8f3ba4e8 | 391 | std::string URI; |
3174e150 | 392 | /** brief A description of this item. */ |
8f3ba4e8 | 393 | std::string Description; |
3174e150 | 394 | /** brief A shorter description of this item. */ |
8f3ba4e8 | 395 | std::string ShortDesc; |
3174e150 | 396 | /** brief The underlying item which is to be downloaded. */ |
8267fe24 AL |
397 | Item *Owner; |
398 | }; | |
92fcbfc1 DK |
399 | /*}}}*/ |
400 | /** \brief A single download queue in a pkgAcquire object. {{{ | |
3174e150 MV |
401 | * |
402 | * \todo Why so many protected values? | |
403 | */ | |
0118833a AL |
404 | class pkgAcquire::Queue |
405 | { | |
b2e465d6 AL |
406 | friend class pkgAcquire; |
407 | friend class pkgAcquire::UriIterator; | |
408 | friend class pkgAcquire::Worker; | |
3174e150 | 409 | |
e92e897a MV |
410 | /** \brief dpointer placeholder (for later in case we need it) */ |
411 | void *d; | |
412 | ||
3174e150 | 413 | /** \brief The next queue in the pkgAcquire object's list of queues. */ |
0118833a AL |
414 | Queue *Next; |
415 | ||
416 | protected: | |
3b5421b4 | 417 | |
3174e150 | 418 | /** \brief A single item placed in this queue. */ |
8267fe24 | 419 | struct QItem : pkgAcquire::ItemDesc |
0a8a80e5 | 420 | { |
3174e150 MV |
421 | /** \brief The next item in the queue. */ |
422 | QItem *Next; | |
423 | /** \brief The worker associated with this item, if any. */ | |
c88edf1d | 424 | pkgAcquire::Worker *Worker; |
3174e150 MV |
425 | |
426 | /** \brief Assign the ItemDesc portion of this QItem from | |
427 | * another ItemDesc | |
428 | */ | |
8267fe24 AL |
429 | void operator =(pkgAcquire::ItemDesc const &I) |
430 | { | |
431 | URI = I.URI; | |
432 | Description = I.Description; | |
433 | ShortDesc = I.ShortDesc; | |
434 | Owner = I.Owner; | |
435 | }; | |
436 | }; | |
0a8a80e5 | 437 | |
3174e150 | 438 | /** \brief The name of this queue. */ |
8f3ba4e8 | 439 | std::string Name; |
0a8a80e5 | 440 | |
3174e150 MV |
441 | /** \brief The head of the list of items contained in this queue. |
442 | * | |
443 | * \todo why a by-hand list instead of an STL structure? | |
444 | */ | |
0a8a80e5 | 445 | QItem *Items; |
3174e150 MV |
446 | |
447 | /** \brief The head of the list of workers associated with this queue. | |
448 | * | |
449 | * \todo This is plural because support exists in Queue for | |
450 | * multiple workers. However, it does not appear that there is | |
451 | * any way to actually associate more than one worker with a | |
452 | * queue. | |
453 | * | |
454 | * \todo Why not just use a std::set? | |
455 | */ | |
0a8a80e5 | 456 | pkgAcquire::Worker *Workers; |
3174e150 MV |
457 | |
458 | /** \brief the download scheduler with which this queue is associated. */ | |
0a8a80e5 | 459 | pkgAcquire *Owner; |
3174e150 MV |
460 | |
461 | /** \brief The number of entries in this queue that are currently | |
462 | * being downloaded. | |
463 | */ | |
e7432370 | 464 | signed long PipeDepth; |
3174e150 MV |
465 | |
466 | /** \brief The maximum number of entries that this queue will | |
467 | * attempt to download at once. | |
468 | */ | |
b185acc2 | 469 | unsigned long MaxPipeDepth; |
0118833a AL |
470 | |
471 | public: | |
0a8a80e5 | 472 | |
8171c75b MV |
473 | /** \brief Insert the given fetch request into this queue. |
474 | * | |
475 | * \return \b true if the queuing was successful. May return | |
476 | * \b false if the Item is already in the queue | |
477 | */ | |
c03462c6 | 478 | bool Enqueue(ItemDesc &Item); |
3174e150 MV |
479 | |
480 | /** \brief Remove all fetch requests for the given item from this queue. | |
481 | * | |
482 | * \return \b true if at least one request was removed from the queue. | |
483 | */ | |
bfd22fc0 | 484 | bool Dequeue(Item *Owner); |
0a8a80e5 | 485 | |
3174e150 MV |
486 | /** \brief Locate an item in this queue. |
487 | * | |
488 | * \param URI A URI to match against. | |
489 | * \param Owner A pkgAcquire::Worker to match against. | |
490 | * | |
491 | * \return the first item in the queue whose URI is #URI and that | |
492 | * is being downloaded by #Owner. | |
493 | */ | |
a02db58f | 494 | QItem *FindItem(std::string URI,pkgAcquire::Worker *Owner) APT_PURE; |
3174e150 MV |
495 | |
496 | /** Presumably this should start downloading an item? | |
497 | * | |
498 | * \todo Unimplemented. Implement it or remove? | |
499 | */ | |
73da43e9 | 500 | bool ItemStart(QItem *Itm,unsigned long long Size); |
3174e150 MV |
501 | |
502 | /** \brief Remove the given item from this queue and set its state | |
503 | * to pkgAcquire::Item::StatDone. | |
504 | * | |
505 | * If this is the only queue containing the item, the item is also | |
506 | * removed from the main queue by calling pkgAcquire::Dequeue. | |
507 | * | |
508 | * \param Itm The item to remove. | |
509 | * | |
510 | * \return \b true if no errors are encountered. | |
511 | */ | |
c88edf1d AL |
512 | bool ItemDone(QItem *Itm); |
513 | ||
3174e150 MV |
514 | /** \brief Start the worker process associated with this queue. |
515 | * | |
516 | * If a worker process is already associated with this queue, | |
517 | * this is equivalent to calling Cycle(). | |
518 | * | |
519 | * \return \b true if the startup was successful. | |
520 | */ | |
0a8a80e5 | 521 | bool Startup(); |
3174e150 MV |
522 | |
523 | /** \brief Shut down the worker process associated with this queue. | |
524 | * | |
525 | * \param Final If \b true, then the process is stopped unconditionally. | |
526 | * Otherwise, it is only stopped if it does not need cleanup | |
527 | * as indicated by the pkgAcqMethod::NeedsCleanup member of | |
528 | * its configuration. | |
529 | * | |
530 | * \return \b true. | |
531 | */ | |
8e5fc8f5 | 532 | bool Shutdown(bool Final); |
3174e150 MV |
533 | |
534 | /** \brief Send idle items to the worker process. | |
535 | * | |
536 | * Fills up the pipeline by inserting idle items into the worker's queue. | |
537 | */ | |
93bf083d | 538 | bool Cycle(); |
3174e150 MV |
539 | |
540 | /** \brief Check for items that could be enqueued. | |
541 | * | |
542 | * Call this after an item placed in multiple queues has gone from | |
543 | * the pkgAcquire::Item::StatFetching state to the | |
544 | * pkgAcquire::Item::StatIdle state, to possibly refill an empty queue. | |
545 | * This is an alias for Cycle(). | |
546 | * | |
547 | * \todo Why both this and Cycle()? Are they expected to be | |
548 | * different someday? | |
549 | */ | |
be4401bf | 550 | void Bump(); |
0a8a80e5 | 551 | |
3174e150 MV |
552 | /** \brief Create a new Queue. |
553 | * | |
554 | * \param Name The name of the new queue. | |
555 | * \param Owner The download process that owns the new queue. | |
556 | */ | |
8f3ba4e8 | 557 | Queue(std::string Name,pkgAcquire *Owner); |
3174e150 MV |
558 | |
559 | /** Shut down all the worker processes associated with this queue | |
560 | * and empty the queue. | |
561 | */ | |
e92e897a | 562 | virtual ~Queue(); |
0118833a | 563 | }; |
92fcbfc1 DK |
564 | /*}}}*/ |
565 | /** \brief Iterates over all the URIs being fetched by a pkgAcquire object. {{{*/ | |
f7a08e33 AL |
566 | class pkgAcquire::UriIterator |
567 | { | |
e92e897a MV |
568 | /** \brief dpointer placeholder (for later in case we need it) */ |
569 | void *d; | |
570 | ||
3174e150 | 571 | /** The next queue to iterate over. */ |
f7a08e33 | 572 | pkgAcquire::Queue *CurQ; |
3174e150 | 573 | /** The item that we currently point at. */ |
f7a08e33 AL |
574 | pkgAcquire::Queue::QItem *CurItem; |
575 | ||
576 | public: | |
577 | ||
296bdfcf | 578 | inline void operator ++() {operator ++(0);}; |
3174e150 | 579 | |
f7a08e33 AL |
580 | void operator ++(int) |
581 | { | |
582 | CurItem = CurItem->Next; | |
583 | while (CurItem == 0 && CurQ != 0) | |
584 | { | |
585 | CurItem = CurQ->Items; | |
586 | CurQ = CurQ->Next; | |
587 | } | |
588 | }; | |
589 | ||
f7a08e33 AL |
590 | inline pkgAcquire::ItemDesc const *operator ->() const {return CurItem;}; |
591 | inline bool operator !=(UriIterator const &rhs) const {return rhs.CurQ != CurQ || rhs.CurItem != CurItem;}; | |
592 | inline bool operator ==(UriIterator const &rhs) const {return rhs.CurQ == CurQ && rhs.CurItem == CurItem;}; | |
593 | ||
3174e150 MV |
594 | /** \brief Create a new UriIterator. |
595 | * | |
596 | * \param Q The queue over which this UriIterator should iterate. | |
597 | */ | |
25613a61 | 598 | UriIterator(pkgAcquire::Queue *Q) : d(NULL), CurQ(Q), CurItem(0) |
f7a08e33 AL |
599 | { |
600 | while (CurItem == 0 && CurQ != 0) | |
601 | { | |
602 | CurItem = CurQ->Items; | |
603 | CurQ = CurQ->Next; | |
604 | } | |
605 | } | |
e92e897a | 606 | virtual ~UriIterator() {}; |
f7a08e33 | 607 | }; |
92fcbfc1 DK |
608 | /*}}}*/ |
609 | /** \brief Information about the properties of a single acquire method. {{{*/ | |
0118833a AL |
610 | struct pkgAcquire::MethodConfig |
611 | { | |
e92e897a MV |
612 | /** \brief dpointer placeholder (for later in case we need it) */ |
613 | void *d; | |
614 | ||
3174e150 MV |
615 | /** \brief The next link on the acquire method list. |
616 | * | |
617 | * \todo Why not an STL container? | |
618 | */ | |
3b5421b4 AL |
619 | MethodConfig *Next; |
620 | ||
3174e150 | 621 | /** \brief The name of this acquire method (e.g., http). */ |
8f3ba4e8 | 622 | std::string Access; |
0118833a | 623 | |
3174e150 | 624 | /** \brief The implementation version of this acquire method. */ |
8f3ba4e8 | 625 | std::string Version; |
3174e150 MV |
626 | |
627 | /** \brief If \b true, only one download queue should be created for this | |
628 | * method. | |
629 | */ | |
0118833a | 630 | bool SingleInstance; |
3174e150 MV |
631 | |
632 | /** \brief If \b true, this method supports pipelined downloading. */ | |
0a8a80e5 | 633 | bool Pipeline; |
3174e150 MV |
634 | |
635 | /** \brief If \b true, the worker process should send the entire | |
636 | * APT configuration tree to the fetch subprocess when it starts | |
637 | * up. | |
638 | */ | |
0a8a80e5 | 639 | bool SendConfig; |
3174e150 MV |
640 | |
641 | /** \brief If \b true, this fetch method does not require network access; | |
642 | * all files are to be acquired from the local disk. | |
643 | */ | |
e331f6ed | 644 | bool LocalOnly; |
3174e150 MV |
645 | |
646 | /** \brief If \b true, the subprocess has to carry out some cleanup | |
647 | * actions before shutting down. | |
648 | * | |
649 | * For instance, the cdrom method needs to unmount the CD after it | |
650 | * finishes. | |
651 | */ | |
8e5fc8f5 | 652 | bool NeedsCleanup; |
3174e150 MV |
653 | |
654 | /** \brief If \b true, this fetch method acquires files from removable media. */ | |
459681d3 | 655 | bool Removable; |
8e5fc8f5 | 656 | |
3174e150 MV |
657 | /** \brief Set up the default method parameters. |
658 | * | |
659 | * All fields are initialized to NULL, "", or \b false as | |
660 | * appropriate. | |
661 | */ | |
0118833a | 662 | MethodConfig(); |
e92e897a MV |
663 | |
664 | /* \brief Destructor, empty currently */ | |
665 | virtual ~MethodConfig() {}; | |
0118833a | 666 | }; |
92fcbfc1 DK |
667 | /*}}}*/ |
668 | /** \brief A monitor object for downloads controlled by the pkgAcquire class. {{{ | |
3174e150 MV |
669 | * |
670 | * \todo Why protected members? | |
3174e150 | 671 | */ |
8267fe24 AL |
672 | class pkgAcquireStatus |
673 | { | |
e92e897a MV |
674 | /** \brief dpointer placeholder (for later in case we need it) */ |
675 | void *d; | |
676 | ||
b98f2859 AL |
677 | protected: |
678 | ||
3174e150 | 679 | /** \brief The last time at which this monitor object was updated. */ |
b98f2859 | 680 | struct timeval Time; |
3174e150 MV |
681 | |
682 | /** \brief The time at which the download started. */ | |
b98f2859 | 683 | struct timeval StartTime; |
3174e150 MV |
684 | |
685 | /** \brief The number of bytes fetched as of the previous call to | |
686 | * pkgAcquireStatus::Pulse, including local items. | |
687 | */ | |
dbbc5494 | 688 | unsigned long long LastBytes; |
3174e150 MV |
689 | |
690 | /** \brief The current rate of download as of the most recent call | |
691 | * to pkgAcquireStatus::Pulse, in bytes per second. | |
692 | */ | |
dbbc5494 | 693 | unsigned long long CurrentCPS; |
3174e150 MV |
694 | |
695 | /** \brief The number of bytes fetched as of the most recent call | |
696 | * to pkgAcquireStatus::Pulse, including local items. | |
697 | */ | |
dbbc5494 | 698 | unsigned long long CurrentBytes; |
3174e150 MV |
699 | |
700 | /** \brief The total number of bytes that need to be fetched. | |
701 | * | |
702 | * \warning This member is inaccurate, as new items might be | |
703 | * enqueued while the download is in progress! | |
704 | */ | |
dbbc5494 | 705 | unsigned long long TotalBytes; |
3174e150 MV |
706 | |
707 | /** \brief The total number of bytes accounted for by items that | |
708 | * were successfully fetched. | |
709 | */ | |
dbbc5494 | 710 | unsigned long long FetchedBytes; |
3174e150 MV |
711 | |
712 | /** \brief The amount of time that has elapsed since the download | |
713 | * started. | |
714 | */ | |
dbbc5494 | 715 | unsigned long long ElapsedTime; |
3174e150 MV |
716 | |
717 | /** \brief The total number of items that need to be fetched. | |
718 | * | |
719 | * \warning This member is inaccurate, as new items might be | |
720 | * enqueued while the download is in progress! | |
721 | */ | |
d568ed2d | 722 | unsigned long TotalItems; |
3174e150 MV |
723 | |
724 | /** \brief The number of items that have been successfully downloaded. */ | |
d568ed2d | 725 | unsigned long CurrentItems; |
b98f2859 | 726 | |
96c6cab1 MV |
727 | /** \brief The estimated percentage of the download (0-100) |
728 | */ | |
729 | double Percent; | |
730 | ||
8267fe24 AL |
731 | public: |
732 | ||
3174e150 MV |
733 | /** \brief If \b true, the download scheduler should call Pulse() |
734 | * at the next available opportunity. | |
735 | */ | |
8267fe24 | 736 | bool Update; |
3174e150 MV |
737 | |
738 | /** \brief If \b true, extra Pulse() invocations will be performed. | |
739 | * | |
740 | * With this option set, Pulse() will be called every time that a | |
741 | * download item starts downloading, finishes downloading, or | |
742 | * terminates with an error. | |
743 | */ | |
c5ccf175 AL |
744 | bool MorePulses; |
745 | ||
3174e150 MV |
746 | /** \brief Invoked when a local or remote file has been completely fetched. |
747 | * | |
748 | * \param Size The size of the file fetched. | |
749 | * | |
750 | * \param ResumePoint How much of the file was already fetched. | |
751 | */ | |
73da43e9 | 752 | virtual void Fetched(unsigned long long Size,unsigned long long ResumePoint); |
b98f2859 | 753 | |
3174e150 MV |
754 | /** \brief Invoked when the user should be prompted to change the |
755 | * inserted removable media. | |
756 | * | |
757 | * This method should not return until the user has confirmed to | |
758 | * the user interface that the media change is complete. | |
759 | * | |
760 | * \param Media The name of the media type that should be changed. | |
761 | * | |
762 | * \param Drive The identifying name of the drive whose media | |
763 | * should be changed. | |
764 | * | |
765 | * \return \b true if the user confirms the media change, \b | |
766 | * false if it is cancelled. | |
767 | * | |
768 | * \todo This is a horrible blocking monster; it should be CPSed | |
769 | * with prejudice. | |
770 | */ | |
8f3ba4e8 | 771 | virtual bool MediaChange(std::string Media,std::string Drive) = 0; |
542ec555 | 772 | |
3174e150 MV |
773 | /** \brief Invoked when an item is confirmed to be up-to-date. |
774 | ||
775 | * For instance, when an HTTP download is informed that the file on | |
776 | * the server was not modified. | |
777 | */ | |
727f18af | 778 | virtual void IMSHit(pkgAcquire::ItemDesc &/*Itm*/) {}; |
3174e150 MV |
779 | |
780 | /** \brief Invoked when some of an item's data is fetched. */ | |
727f18af | 781 | virtual void Fetch(pkgAcquire::ItemDesc &/*Itm*/) {}; |
3174e150 MV |
782 | |
783 | /** \brief Invoked when an item is successfully and completely fetched. */ | |
727f18af | 784 | virtual void Done(pkgAcquire::ItemDesc &/*Itm*/) {}; |
3174e150 MV |
785 | |
786 | /** \brief Invoked when the process of fetching an item encounters | |
787 | * a fatal error. | |
788 | */ | |
727f18af | 789 | virtual void Fail(pkgAcquire::ItemDesc &/*Itm*/) {}; |
3174e150 MV |
790 | |
791 | /** \brief Periodically invoked while the Acquire process is underway. | |
792 | * | |
793 | * Subclasses should first call pkgAcquireStatus::Pulse(), then | |
794 | * update their status output. The download process is blocked | |
795 | * while Pulse() is being called. | |
796 | * | |
797 | * \return \b false if the user asked to cancel the whole Acquire process. | |
798 | * | |
799 | * \see pkgAcquire::Run | |
800 | */ | |
801 | virtual bool Pulse(pkgAcquire *Owner); | |
802 | ||
803 | /** \brief Invoked when the Acquire process starts running. */ | |
b98f2859 | 804 | virtual void Start(); |
3174e150 MV |
805 | |
806 | /** \brief Invoked when the Acquire process stops running. */ | |
b98f2859 | 807 | virtual void Stop(); |
a6568219 | 808 | |
3174e150 | 809 | /** \brief Initialize all counters to 0 and the time to the current time. */ |
b98f2859 | 810 | pkgAcquireStatus(); |
8267fe24 AL |
811 | virtual ~pkgAcquireStatus() {}; |
812 | }; | |
92fcbfc1 | 813 | /*}}}*/ |
3174e150 MV |
814 | /** @} */ |
815 | ||
0118833a | 816 | #endif |