1 // -*- mode: cpp; mode: fold -*-
3 // $Id: acquire-worker.h,v 1.12 2001/02/20 07:03:17 jgg Exp $
4 /* ######################################################################
6 Acquire Worker - Worker process manager
8 Each worker class is associated with exaclty one subprocess.
10 ##################################################################### */
13 /** \addtogroup acquire
16 * \file acquire-worker.h
19 #ifndef PKGLIB_ACQUIRE_WORKER_H
20 #define PKGLIB_ACQUIRE_WORKER_H
22 #include <apt-pkg/acquire.h>
23 #include <apt-pkg/weakptr.h>
25 #include <sys/types.h>
29 /** \brief A fetch subprocess.
31 * A worker process is responsible for one stage of the fetch. This
32 * class encapsulates the communications protocol between the master
33 * process and the worker, from the master end.
35 * Each worker is intrinsically placed on two linked lists. The
36 * Queue list (maintained in the #NextQueue variable) is maintained
37 * by the pkgAcquire::Queue class; it represents the set of workers
38 * assigned to a particular queue. The Acquire list (maintained in
39 * the #NextAcquire variable) is maintained by the pkgAcquire class;
40 * it represents the set of active workers for a particular
43 * \todo Like everything else in the Acquire system, this has way too
44 * many protected items.
46 * \sa pkgAcqMethod, pkgAcquire::Item, pkgAcquire
48 class pkgAcquire::Worker
: public WeakPointable
50 /** \brief dpointer placeholder (for later in case we need it) */
53 friend class pkgAcquire
;
58 /** \brief The next link on the Queue list.
60 * \todo This is always NULL; is it just for future use?
64 /** \brief The next link on the Acquire list. */
67 /** \brief The Queue with which this worker is associated. */
70 /** \brief The download progress indicator to which progress
71 * messages should be sent.
73 pkgAcquireStatus
*Log
;
75 /** \brief The configuration of this method. On startup, the
76 * target of this pointer is filled in with basic data about the
77 * method, as reported by the worker.
81 /** \brief The access method to be used by this worker.
83 * \todo Doesn't this duplicate Config->Access?
87 /** \brief The PID of the subprocess. */
90 /** \brief A file descriptor connected to the standard output of
93 * Used to read messages and data from the subprocess.
97 /** \brief A file descriptor connected to the standard input of the
100 * Used to send commands and configuration data to the subprocess.
104 /** \brief Set to \b true if the worker is in a state in which it
105 * might generate data or command responses.
107 * \todo Is this right? It's a guess.
111 /** \brief Set to \b true if the worker is in a state in which it
112 * is legal to send commands to it.
114 * \todo Is this right?
118 /** If \b true, debugging output will be sent to std::clog. */
121 /** \brief The raw text values of messages received from the
122 * worker, in sequence.
124 std::vector
<std::string
> MessageQueue
;
126 /** \brief Buffers pending writes to the subprocess.
128 * \todo Wouldn't a std::dequeue be more appropriate?
130 std::string OutQueue
;
132 /** \brief Common code for the constructor.
134 * Initializes NextQueue and NextAcquire to NULL; Process, InFd,
135 * and OutFd to -1, OutReady and InReady to \b false, and Debug
140 /** \brief Retrieve any available messages from the subprocess.
142 * The messages are retrieved as in \link strutl.h ReadMessages()\endlink, and
143 * #MethodFailure() is invoked if an error occurs; in particular,
144 * if the pipe to the subprocess dies unexpectedly while a message
147 * \return \b true if the messages were successfully read, \b
152 /** \brief Parse and dispatch pending messages.
154 * This dispatches the message in a manner appropriate for its
157 * \todo Several message types lack separate handlers.
159 * \sa Capabilities(), SendConfiguration(), MediaChange()
163 /** \brief Read and dispatch any pending messages from the
166 * \return \b false if the subprocess died unexpectedly while a
167 * message was being transmitted.
171 /** \brief Send any pending commands to the subprocess.
173 * This method will fail if there is no pending output.
175 * \return \b true if all commands were succeeded, \b false if an
176 * error occurred (in which case MethodFailure() will be invoked).
180 /** \brief Handle a 100 Capabilities response from the subprocess.
182 * \param Message the raw text of the message from the subprocess.
184 * The message will be parsed and its contents used to fill
185 * #Config. If #Config is NULL, this routine is a NOP.
189 bool Capabilities(std::string Message
);
191 /** \brief Send a 601 Configuration message (containing the APT
192 * configuration) to the subprocess.
194 * The APT configuration will be send to the subprocess in a
195 * message of the following form:
199 * Config-Item: Fully-Qualified-Item=Val
200 * Config-Item: Fully-Qualified-Item=Val
204 * \return \b true if the command was successfully sent, \b false
207 bool SendConfiguration();
209 /** \brief Handle a 403 Media Change message.
211 * \param Message the raw text of the message; the Media field
212 * indicates what type of media should be changed, and the Drive
213 * field indicates where the media is located.
215 * Invokes pkgAcquireStatus::MediaChange(Media, Drive) to ask the
216 * user to swap disks; informs the subprocess of the result (via
217 * 603 Media Changed, with the Failed field set to \b true if the
218 * user cancelled the media change).
220 bool MediaChange(std::string Message
);
222 /** \brief Invoked when the worked process dies unexpectedly.
224 * Waits for the subprocess to terminate and generates an error if
225 * it terminated abnormally, then closes and blanks out all file
226 * descriptors. Discards all pending messages from the
231 bool MethodFailure();
233 /** \brief Invoked when a fetch job is completed, either
234 * successfully or unsuccessfully.
236 * Resets the status information for the worker process.
242 /** \brief The queue entry that is currently being downloaded. */
243 pkgAcquire::Queue::QItem
*CurrentItem
;
245 /** \brief The most recent status string received from the
250 /** \brief How many bytes of the file have been downloaded. Zero
251 * if the current progress of the file cannot be determined.
253 unsigned long long CurrentSize
;
255 /** \brief The total number of bytes to be downloaded. Zero if the
256 * total size of the final is unknown.
258 unsigned long long TotalSize
;
260 /** \brief How much of the file was already downloaded prior to
261 * starting this worker.
263 unsigned long long ResumePoint
;
265 /** \brief Tell the subprocess to download the given item.
267 * \param Item the item to queue up.
268 * \return \b true if the item was successfully enqueued.
270 * Queues up a 600 URI Acquire message for the given item to be
271 * sent at the next possible moment. Does \e not flush the output
274 bool QueueItem(pkgAcquire::Queue::QItem
*Item
);
276 /** \brief Start up the worker and fill in #Config.
278 * Reads the first message from the worker, which is assumed to be
279 * a 100 Capabilities message.
281 * \return \b true if all operations completed successfully.
285 /** \brief Update the worker statistics (CurrentSize, TotalSize,
290 /** \return The fetch method configuration. */
291 inline const MethodConfig
*GetConf() const {return Config
;};
293 /** \brief Create a new Worker to download files.
295 * \param OwnerQ The queue into which this worker should be
298 * \param Config A location in which to store information about
301 * \param Log The download progress indicator that should be used
302 * to report the progress of this worker.
304 Worker(Queue
*OwnerQ
,MethodConfig
*Config
,pkgAcquireStatus
*Log
);
306 /** \brief Create a new Worker that should just retrieve
307 * information about the fetch method.
309 * Nothing in particular forces you to refrain from actually
310 * downloading stuff, but the various status callbacks won't be
313 * \param Config A location in which to store information about
316 Worker(MethodConfig
*Config
);
318 /** \brief Clean up this worker.
320 * Closes the file descriptors; if MethodConfig::NeedsCleanup is
321 * \b false, also rudely interrupts the worker with a SIGINT.