apt-pkg/acquire.h

   1 // -*- mode: cpp; mode: fold -*-
   2 // Description                                                          /*{{{*/
   3 // $Id: acquire.h,v 1.22 1999/07/03 03:10:35 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 Item;
  56    friend 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    unsigned long TotalNeeded();
 116    unsigned long FetchNeeded();
 117    unsigned long PartialPresent();
 118
 119    pkgAcquire(pkgAcquireStatus *Log = 0);
 120    ~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 pkgAcquire;
 136    friend pkgAcquire::UriIterator;
 137    Queue *Next;
 138
 139    protected:
 140
 141    // Queued item
 142    struct QItem : pkgAcquire::ItemDesc
 143    {
 144       QItem *Next;
 145       pkgAcquire::Worker *Worker;
 146
 147       void operator =(pkgAcquire::ItemDesc const &I)
 148       {
 149          URI = I.URI;
 150          Description = I.Description;
 151          ShortDesc = I.ShortDesc;
 152          Owner = I.Owner;
 153       };
 154    };
 155
 156    // Name of the queue
 157    string Name;
 158
 159    // Items queued into this queue
 160    QItem *Items;
 161    pkgAcquire::Worker *Workers;
 162    pkgAcquire *Owner;
 163    signed long PipeDepth;
 164    unsigned long MaxPipeDepth;
 165
 166    public:
 167
 168    // Put an item into this queue
 169    void Enqueue(ItemDesc &Item);
 170    bool Dequeue(Item *Owner);
 171
 172    // Find a Queued item
 173    QItem *FindItem(string URI,pkgAcquire::Worker *Owner);
 174    bool ItemStart(QItem *Itm,unsigned long Size);
 175    bool ItemDone(QItem *Itm);
 176
 177    bool Startup();
 178    bool Shutdown();
 179    bool Cycle();
 180    void Bump();
 181
 182    Queue(string Name,pkgAcquire *Owner);
 183    ~Queue();
 184 };
 185
 186 class pkgAcquire::UriIterator
 187 {
 188    pkgAcquire::Queue *CurQ;
 189    pkgAcquire::Queue::QItem *CurItem;
 190
 191    public:
 192
 193    // Advance to the next item
 194    inline void operator ++() {operator ++();};
 195    void operator ++(int)
 196    {
 197       CurItem = CurItem->Next;
 198       while (CurItem == 0 && CurQ != 0)
 199       {
 200          CurItem = CurQ->Items;
 201          CurQ = CurQ->Next;
 202       }
 203    };
 204
 205    // Accessors
 206    inline pkgAcquire::ItemDesc const *operator ->() const {return CurItem;};
 207    inline bool operator !=(UriIterator const &rhs) const {return rhs.CurQ != CurQ || rhs.CurItem != CurItem;};
 208    inline bool operator ==(UriIterator const &rhs) const {return rhs.CurQ == CurQ && rhs.CurItem == CurItem;};
 209
 210    UriIterator(pkgAcquire::Queue *Q) : CurQ(Q), CurItem(0)
 211    {
 212       while (CurItem == 0 && CurQ != 0)
 213       {
 214          CurItem = CurQ->Items;
 215          CurQ = CurQ->Next;
 216       }
 217    }
 218 };
 219
 220 // Configuration information from each method
 221 struct pkgAcquire::MethodConfig
 222 {
 223    MethodConfig *Next;
 224
 225    string Access;
 226
 227    string Version;
 228    bool SingleInstance;
 229    bool Pipeline;
 230    bool SendConfig;
 231    bool LocalOnly;
 232
 233    MethodConfig();
 234 };
 235
 236 class pkgAcquireStatus
 237 {
 238    protected:
 239
 240    struct timeval Time;
 241    struct timeval StartTime;
 242    unsigned long LastBytes;
 243    double CurrentCPS;
 244    unsigned long CurrentBytes;
 245    unsigned long TotalBytes;
 246    unsigned long FetchedBytes;
 247    unsigned long ElapsedTime;
 248    unsigned long TotalItems;
 249    unsigned long CurrentItems;
 250
 251    public:
 252
 253    bool Update;
 254
 255    // Called by items when they have finished a real download
 256    virtual void Fetched(unsigned long Size,unsigned long ResumePoint);
 257
 258    // Called to change media
 259    virtual bool MediaChange(string Media,string Drive) = 0;
 260
 261    // Each of these is called by the workers when an event occures
 262    virtual void IMSHit(pkgAcquire::ItemDesc &Itm) {};
 263    virtual void Fetch(pkgAcquire::ItemDesc &Itm) {};
 264    virtual void Done(pkgAcquire::ItemDesc &Itm) {};
 265    virtual void Fail(pkgAcquire::ItemDesc &Itm) {};
 266    virtual bool Pulse(pkgAcquire *Owner); // returns false on user cancel
 267    virtual void Start();
 268    virtual void Stop();
 269
 270    pkgAcquireStatus();
 271    virtual ~pkgAcquireStatus() {};
 272 };
 273
 274 #endif