apt-pkg/acquire.h

   1 // -*- mode: cpp; mode: fold -*-
   2 // Description                                                          /*{{{*/
   3 // $Id: acquire.h,v 1.25 1999/10/18 00:37: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    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 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(bool Final);
 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    bool NeedsCleanup;
 233
 234    MethodConfig();
 235 };
 236
 237 class pkgAcquireStatus
 238 {
 239    protected:
 240
 241    struct timeval Time;
 242    struct timeval StartTime;
 243    unsigned long LastBytes;
 244    double CurrentCPS;
 245    unsigned long CurrentBytes;
 246    unsigned long TotalBytes;
 247    unsigned long FetchedBytes;
 248    unsigned long ElapsedTime;
 249    unsigned long TotalItems;
 250    unsigned long CurrentItems;
 251
 252    public:
 253
 254    bool Update;
 255
 256    // Called by items when they have finished a real download
 257    virtual void Fetched(unsigned long Size,unsigned long ResumePoint);
 258
 259    // Called to change media
 260    virtual bool MediaChange(string Media,string Drive) = 0;
 261
 262    // Each of these is called by the workers when an event occures
 263    virtual void IMSHit(pkgAcquire::ItemDesc &/*Itm*/) {};
 264    virtual void Fetch(pkgAcquire::ItemDesc &/*Itm*/) {};
 265    virtual void Done(pkgAcquire::ItemDesc &/*Itm*/) {};
 266    virtual void Fail(pkgAcquire::ItemDesc &/*Itm*/) {};
 267    virtual bool Pulse(pkgAcquire *Owner); // returns false on user cancel
 268    virtual void Start();
 269    virtual void Stop();
 270
 271    pkgAcquireStatus();
 272    virtual ~pkgAcquireStatus() {};
 273 };
 274
 275 #endif