apt-pkg/acquire.h

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