apt-pkg/acquire.h

   1 // -*- mode: cpp; mode: fold -*-
   2 // Description                                                          /*{{{*/
   3 // $Id: acquire.h,v 1.28 2001/02/20 07:03:17 jgg Exp $
   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                                                                         /*}}}*/
  32 #ifndef PKGLIB_ACQUIRE_H
  33 #define PKGLIB_ACQUIRE_H
  34
  35 #include <vector>
  36 #include <string>
  37
  38 #ifdef __GNUG__
  39 #pragma interface "apt-pkg/acquire.h"
  40 #endif
  41
  42 #include <sys/time.h>
  43 #include <unistd.h>
  44
  45 class pkgAcquireStatus;
  46 class pkgAcquire
  47 {
  48    public:
  49
  50    class Item;
  51    class Queue;
  52    class Worker;
  53    struct MethodConfig;
  54    struct ItemDesc;
  55    friend class Item;
  56    friend class Queue;
  57
  58    protected:
  59
  60    // List of items to fetch
  61    vector<Item *> Items;
  62
  63    // List of active queues and fetched method configuration parameters
  64    Queue *Queues;
  65    Worker *Workers;
  66    MethodConfig *Configs;
  67    pkgAcquireStatus *Log;
  68    unsigned long ToFetch;
  69
  70    // Configurable parameters for the schedular
  71    enum {QueueHost,QueueAccess} QueueMode;
  72    bool Debug;
  73    bool Running;
  74
  75    void Add(Item *Item);
  76    void Remove(Item *Item);
  77    void Add(Worker *Work);
  78    void Remove(Worker *Work);
  79
  80    void Enqueue(ItemDesc &Item);
  81    void Dequeue(Item *Item);
  82    string QueueName(string URI,MethodConfig const *&Config);
  83
  84    // FDSET managers for derived classes
  85    virtual void SetFds(int &Fd,fd_set *RSet,fd_set *WSet);
  86    virtual void RunFds(fd_set *RSet,fd_set *WSet);
  87
  88    // A queue calls this when it dequeues an item
  89    void Bump();
  90
  91    public:
  92
  93    MethodConfig *GetConfig(string Access);
  94
  95    enum RunResult {Continue,Failed,Cancelled};
  96
  97    RunResult Run();
  98    void Shutdown();
  99
 100    // Simple iteration mechanism
 101    inline Worker *WorkersBegin() {return Workers;};
 102    Worker *WorkerStep(Worker *I);
 103    inline Item **ItemsBegin() {return Items.begin();};
 104    inline Item **ItemsEnd() {return Items.end();};
 105
 106    // Iterate over queued Item URIs
 107    class UriIterator;
 108    UriIterator UriBegin();
 109    UriIterator UriEnd();
 110
 111    // Cleans out the download dir
 112    bool Clean(string Dir);
 113
 114    // Returns the size of the total download set
 115    double TotalNeeded();
 116    double FetchNeeded();
 117    double PartialPresent();
 118
 119    pkgAcquire(pkgAcquireStatus *Log = 0);
 120    virtual ~pkgAcquire();
 121 };
 122
 123 // Description of an Item+URI
 124 struct pkgAcquire::ItemDesc
 125 {
 126    string URI;
 127    string Description;
 128    string ShortDesc;
 129    Item *Owner;
 130 };
 131
 132 // List of possible items queued for download.
 133 class pkgAcquire::Queue
 134 {
 135    friend class pkgAcquire;
 136    friend class pkgAcquire::UriIterator;
 137    friend class pkgAcquire::Worker;
 138    Queue *Next;
 139
 140    protected:
 141
 142    // Queued item
 143    struct QItem : pkgAcquire::ItemDesc
 144    {
 145       QItem *Next;
 146       pkgAcquire::Worker *Worker;
 147
 148       void operator =(pkgAcquire::ItemDesc const &I)
 149       {
 150          URI = I.URI;
 151          Description = I.Description;
 152          ShortDesc = I.ShortDesc;
 153          Owner = I.Owner;
 154       };
 155    };
 156
 157    // Name of the queue
 158    string Name;
 159
 160    // Items queued into this queue
 161    QItem *Items;
 162    pkgAcquire::Worker *Workers;
 163    pkgAcquire *Owner;
 164    signed long PipeDepth;
 165    unsigned long MaxPipeDepth;
 166
 167    public:
 168
 169    // Put an item into this queue
 170    void Enqueue(ItemDesc &Item);
 171    bool Dequeue(Item *Owner);
 172
 173    // Find a Queued item
 174    QItem *FindItem(string URI,pkgAcquire::Worker *Owner);
 175    bool ItemStart(QItem *Itm,unsigned long Size);
 176    bool ItemDone(QItem *Itm);
 177
 178    bool Startup();
 179    bool Shutdown(bool Final);
 180    bool Cycle();
 181    void Bump();
 182
 183    Queue(string Name,pkgAcquire *Owner);
 184    ~Queue();
 185 };
 186
 187 class pkgAcquire::UriIterator
 188 {
 189    pkgAcquire::Queue *CurQ;
 190    pkgAcquire::Queue::QItem *CurItem;
 191
 192    public:
 193
 194    // Advance to the next item
 195    inline void operator ++() {operator ++();};
 196    void operator ++(int)
 197    {
 198       CurItem = CurItem->Next;
 199       while (CurItem == 0 && CurQ != 0)
 200       {
 201          CurItem = CurQ->Items;
 202          CurQ = CurQ->Next;
 203       }
 204    };
 205
 206    // Accessors
 207    inline pkgAcquire::ItemDesc const *operator ->() const {return CurItem;};
 208    inline bool operator !=(UriIterator const &rhs) const {return rhs.CurQ != CurQ || rhs.CurItem != CurItem;};
 209    inline bool operator ==(UriIterator const &rhs) const {return rhs.CurQ == CurQ && rhs.CurItem == CurItem;};
 210
 211    UriIterator(pkgAcquire::Queue *Q) : CurQ(Q), CurItem(0)
 212    {
 213       while (CurItem == 0 && CurQ != 0)
 214       {
 215          CurItem = CurQ->Items;
 216          CurQ = CurQ->Next;
 217       }
 218    }
 219 };
 220
 221 // Configuration information from each method
 222 struct pkgAcquire::MethodConfig
 223 {
 224    MethodConfig *Next;
 225
 226    string Access;
 227
 228    string Version;
 229    bool SingleInstance;
 230    bool Pipeline;
 231    bool SendConfig;
 232    bool LocalOnly;
 233    bool NeedsCleanup;
 234    bool Removable;
 235
 236    MethodConfig();
 237 };
 238
 239 class pkgAcquireStatus
 240 {
 241    protected:
 242
 243    struct timeval Time;
 244    struct timeval StartTime;
 245    double LastBytes;
 246    double CurrentCPS;
 247    double CurrentBytes;
 248    double TotalBytes;
 249    double FetchedBytes;
 250    unsigned long ElapsedTime;
 251    unsigned long TotalItems;
 252    unsigned long CurrentItems;
 253
 254    public:
 255
 256    bool Update;
 257    bool MorePulses;
 258
 259    // Called by items when they have finished a real download
 260    virtual void Fetched(unsigned long Size,unsigned long ResumePoint);
 261
 262    // Called to change media
 263    virtual bool MediaChange(string Media,string Drive) = 0;
 264
 265    // Each of these is called by the workers when an event occures
 266    virtual void IMSHit(pkgAcquire::ItemDesc &/*Itm*/) {};
 267    virtual void Fetch(pkgAcquire::ItemDesc &/*Itm*/) {};
 268    virtual void Done(pkgAcquire::ItemDesc &/*Itm*/) {};
 269    virtual void Fail(pkgAcquire::ItemDesc &/*Itm*/) {};
 270    virtual bool Pulse(pkgAcquire *Owner); // returns false on user cancel
 271    virtual void Start();
 272    virtual void Stop();
 273
 274    pkgAcquireStatus();
 275    virtual ~pkgAcquireStatus() {};
 276 };
 277
 278 #endif