You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

323 lines
9.3 KiB

  1. // -*- mode: cpp; mode: fold -*-
  2. // Description /*{{{*/
  3. // $Id: acquire-worker.h,v 1.12 2001/02/20 07:03:17 jgg Exp $
  4. /* ######################################################################
  5. Acquire Worker - Worker process manager
  6. Each worker class is associated with exaclty one subprocess.
  7. ##################################################################### */
  8. /*}}}*/
  9. /** \addtogroup acquire
  10. * @{
  11. *
  12. * \file acquire-worker.h
  13. */
  14. #ifndef PKGLIB_ACQUIRE_WORKER_H
  15. #define PKGLIB_ACQUIRE_WORKER_H
  16. #include <apt-pkg/acquire.h>
  17. #include <apt-pkg/weakptr.h>
  18. /** \brief A fetch subprocess.
  19. *
  20. * A worker process is responsible for one stage of the fetch. This
  21. * class encapsulates the communications protocol between the master
  22. * process and the worker, from the master end.
  23. *
  24. * Each worker is intrinsically placed on two linked lists. The
  25. * Queue list (maintained in the #NextQueue variable) is maintained
  26. * by the pkgAcquire::Queue class; it represents the set of workers
  27. * assigned to a particular queue. The Acquire list (maintained in
  28. * the #NextAcquire variable) is maintained by the pkgAcquire class;
  29. * it represents the set of active workers for a particular
  30. * pkgAcquire object.
  31. *
  32. * \todo Like everything else in the Acquire system, this has way too
  33. * many protected items.
  34. *
  35. * \sa pkgAcqMethod, pkgAcquire::Item, pkgAcquire
  36. */
  37. class pkgAcquire::Worker : public WeakPointable
  38. {
  39. friend class pkgAcquire;
  40. protected:
  41. friend class Queue;
  42. /** \brief The next link on the Queue list.
  43. *
  44. * \todo This is always NULL; is it just for future use?
  45. */
  46. Worker *NextQueue;
  47. /** \brief The next link on the Acquire list. */
  48. Worker *NextAcquire;
  49. /** \brief The Queue with which this worker is associated. */
  50. Queue *OwnerQ;
  51. /** \brief The download progress indicator to which progress
  52. * messages should be sent.
  53. */
  54. pkgAcquireStatus *Log;
  55. /** \brief The configuration of this method. On startup, the
  56. * target of this pointer is filled in with basic data about the
  57. * method, as reported by the worker.
  58. */
  59. MethodConfig *Config;
  60. /** \brief The access method to be used by this worker.
  61. *
  62. * \todo Doesn't this duplicate Config->Access?
  63. */
  64. string Access;
  65. /** \brief The PID of the subprocess. */
  66. pid_t Process;
  67. /** \brief A file descriptor connected to the standard output of
  68. * the subprocess.
  69. *
  70. * Used to read messages and data from the subprocess.
  71. */
  72. int InFd;
  73. /** \brief A file descriptor connected to the standard input of the
  74. * subprocess.
  75. *
  76. * Used to send commands and configuration data to the subprocess.
  77. */
  78. int OutFd;
  79. /** \brief Set to \b true if the worker is in a state in which it
  80. * might generate data or command responses.
  81. *
  82. * \todo Is this right? It's a guess.
  83. */
  84. bool InReady;
  85. /** \brief Set to \b true if the worker is in a state in which it
  86. * is legal to send commands to it.
  87. *
  88. * \todo Is this right?
  89. */
  90. bool OutReady;
  91. /** If \b true, debugging output will be sent to std::clog. */
  92. bool Debug;
  93. /** \brief The raw text values of messages received from the
  94. * worker, in sequence.
  95. */
  96. vector<string> MessageQueue;
  97. /** \brief Buffers pending writes to the subprocess.
  98. *
  99. * \todo Wouldn't a std::dequeue be more appropriate?
  100. */
  101. string OutQueue;
  102. /** \brief Common code for the constructor.
  103. *
  104. * Initializes NextQueue and NextAcquire to NULL; Process, InFd,
  105. * and OutFd to -1, OutReady and InReady to \b false, and Debug
  106. * from _config.
  107. */
  108. void Construct();
  109. /** \brief Retrieve any available messages from the subprocess.
  110. *
  111. * The messages are retrieved as in ::ReadMessages(), and
  112. * MessageFailure() is invoked if an error occurs; in particular,
  113. * if the pipe to the subprocess dies unexpectedly while a message
  114. * is being read.
  115. *
  116. * \return \b true if the messages were successfully read, \b
  117. * false otherwise.
  118. */
  119. bool ReadMessages();
  120. /** \brief Parse and dispatch pending messages.
  121. *
  122. * This dispatches the message in a manner appropriate for its
  123. * type.
  124. *
  125. * \todo Several message types lack separate handlers.
  126. *
  127. * \sa Capabilities(), SendConfiguration(), MediaChange()
  128. */
  129. bool RunMessages();
  130. /** \brief Read and dispatch any pending messages from the
  131. * subprocess.
  132. *
  133. * \return \b false if the subprocess died unexpectedly while a
  134. * message was being transmitted.
  135. */
  136. bool InFdReady();
  137. /** \brief Send any pending commands to the subprocess.
  138. *
  139. * This method will fail if there is no pending output.
  140. *
  141. * \return \b true if all commands were succeeded, \b false if an
  142. * error occurred (in which case MethodFailure() will be invoked).
  143. */
  144. bool OutFdReady();
  145. /** \brief Handle a 100 Capabilities response from the subprocess.
  146. *
  147. * \param Message the raw text of the message from the subprocess.
  148. *
  149. * The message will be parsed and its contents used to fill
  150. * #Config. If #Config is NULL, this routine is a NOP.
  151. *
  152. * \return \b true.
  153. */
  154. bool Capabilities(string Message);
  155. /** \brief Send a 601 Configuration message (containing the APT
  156. * configuration) to the subprocess.
  157. *
  158. * The APT configuration will be send to the subprocess in a
  159. * message of the following form:
  160. *
  161. * <pre>
  162. * 601 Configuration
  163. * Config-Item: Fully-Qualified-Item=Val
  164. * Config-Item: Fully-Qualified-Item=Val
  165. * ...
  166. * </pre>
  167. *
  168. * \return \b true if the command was successfully sent, \b false
  169. * otherwise.
  170. */
  171. bool SendConfiguration();
  172. /** \brief Handle a 403 Media Change message.
  173. *
  174. * \param Message the raw text of the message; the Media field
  175. * indicates what type of media should be changed, and the Drive
  176. * field indicates where the media is located.
  177. *
  178. * Invokes pkgAcquireStatus::MediaChange(Media, Drive) to ask the
  179. * user to swap disks; informs the subprocess of the result (via
  180. * 603 Media Changed, with the Failed field set to \b true if the
  181. * user cancelled the media change).
  182. */
  183. bool MediaChange(string Message);
  184. /** \brief Invoked when the worked process dies unexpectedly.
  185. *
  186. * Waits for the subprocess to terminate and generates an error if
  187. * it terminated abnormally, then closes and blanks out all file
  188. * descriptors. Discards all pending messages from the
  189. * subprocess.
  190. *
  191. * \return \b false.
  192. */
  193. bool MethodFailure();
  194. /** \brief Invoked when a fetch job is completed, either
  195. * successfully or unsuccessfully.
  196. *
  197. * Resets the status information for the worker process.
  198. */
  199. void ItemDone();
  200. public:
  201. /** \brief The queue entry that is currently being downloaded. */
  202. pkgAcquire::Queue::QItem *CurrentItem;
  203. /** \brief The most recent status string received from the
  204. * subprocess.
  205. */
  206. string Status;
  207. /** \brief How many bytes of the file have been downloaded. Zero
  208. * if the current progress of the file cannot be determined.
  209. */
  210. unsigned long CurrentSize;
  211. /** \brief The total number of bytes to be downloaded. Zero if the
  212. * total size of the final is unknown.
  213. */
  214. unsigned long TotalSize;
  215. /** \brief How much of the file was already downloaded prior to
  216. * starting this worker.
  217. */
  218. unsigned long ResumePoint;
  219. /** \brief Tell the subprocess to download the given item.
  220. *
  221. * \param Item the item to queue up.
  222. * \return \b true if the item was successfully enqueued.
  223. *
  224. * Queues up a 600 URI Acquire message for the given item to be
  225. * sent at the next possible moment. Does \e not flush the output
  226. * queue.
  227. */
  228. bool QueueItem(pkgAcquire::Queue::QItem *Item);
  229. /** \brief Start up the worker and fill in #Config.
  230. *
  231. * Reads the first message from the worker, which is assumed to be
  232. * a 100 Capabilities message.
  233. *
  234. * \return \b true if all operations completed successfully.
  235. */
  236. bool Start();
  237. /** \brief Update the worker statistics (CurrentSize, TotalSize,
  238. * etc).
  239. */
  240. void Pulse();
  241. /** \return The fetch method configuration. */
  242. inline const MethodConfig *GetConf() const {return Config;};
  243. /** \brief Create a new Worker to download files.
  244. *
  245. * \param OwnerQ The queue into which this worker should be
  246. * placed.
  247. *
  248. * \param Config A location in which to store information about
  249. * the fetch method.
  250. *
  251. * \param Log The download progress indicator that should be used
  252. * to report the progress of this worker.
  253. */
  254. Worker(Queue *OwnerQ,MethodConfig *Config,pkgAcquireStatus *Log);
  255. /** \brief Create a new Worker that should just retrieve
  256. * information about the fetch method.
  257. *
  258. * Nothing in particular forces you to refrain from actually
  259. * downloading stuff, but the various status callbacks won't be
  260. * invoked.
  261. *
  262. * \param Config A location in which to store information about
  263. * the fetch method.
  264. */
  265. Worker(MethodConfig *Config);
  266. /** \brief Clean up this worker.
  267. *
  268. * Closes the file descriptors; if MethodConfig::NeedsCleanup is
  269. * \b false, also rudely interrupts the worker with a SIGINT.
  270. */
  271. ~Worker();
  272. };
  273. /** @} */
  274. #endif