dom/filesystem/FileSystemTaskBase.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   5  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_dom_FileSystemTaskBase_h
   8 #define mozilla_dom_FileSystemTaskBase_h
   9
  10 #include "mozilla/ErrorResult.h"
  11 #include "mozilla/dom/FileSystemRequestParent.h"
  12 #include "mozilla/dom/PFileSystemRequestChild.h"
  13 #include "nsIGlobalObject.h"
  14 #include "nsThreadUtils.h"
  15
  16 namespace mozilla {
  17 namespace dom {
  18
  19 class BlobImpl;
  20 class FileSystemBase;
  21 class FileSystemParams;
  22
  23 /*
  24  * The base class to implement a Task class.
  25  * The file system operations can only be performed in the parent process. In
  26  * order to avoid duplicated code, we used PBackground for child-parent and
  27  * parent-parent communications.
  28  *
  29  * The following diagram illustrates the how a API call from the content page
  30  * starts a task and gets call back results.
  31  *
  32  * The left block is the call sequence inside any process loading content, while
  33  * the right block is the call sequence only inside the parent process.
  34  *
  35  *       Page
  36  *        |
  37  *        | (1)
  38  *  ______|_________________________     |    _________________________________
  39  * |      |                          |   |   |                                 |
  40  * |      |                          |   |   |                                 |
  41  * |      V                          |  IPC  | PBackground thread on           |
  42  * | [new FileSystemTaskChildBase()] |   |   | the parent process              |
  43  * |         |                       |   |   |                                 |
  44  * |         | (2)                   |       |                                 |
  45  * |         V                       |  (3)  |                                 |
  46  * |    [GetRequestParams]------------------->[new FileSystemTaskParentBase()] |
  47  * |                                 |       |          |                      |
  48  * |                                 |   |   |          | (4)   _____________  |
  49  * |                                 |   |   |          |      |             | |
  50  * |                                 |   |   |          |      | I/O Thread  | |
  51  * |                                 |   |   |          |      |             | |
  52  * |                                 |   |   |          ---------> [IOWork]  | |
  53  * |                                 |  IPC  |                 |     |       | |
  54  * |                                 |   |   |                 |     | (5)   | |
  55  * |                                 |   |   |          --------------       | |
  56  * |                                 |   |   |          |      |_____________| |
  57  * |                                 |   |   |          |                      |
  58  * |                                 |   |   |          V                      |
  59  * |                                 |   |   |     [HandleResult]              |
  60  * |                                 |   |   |          |                      |
  61  * |                                 |       |          | (6)                  |
  62  * |                                 |  (7)  |          V                      |
  63  * |   [SetRequestResult]<---------------------[GetRequestResult]              |
  64  * |       |                         |       |                                 |
  65  * |       | (8)                     |   |   |                                 |
  66  * |       V                         |   |   |                                 |
  67  * |[HandlerCallback]                |  IPC  |                                 |
  68  * |_______|_________________________|   |   |_________________________________|
  69  *         |                             |
  70  *         V
  71  *        Page
  72  *
  73  * 1. From the process that is handling the request
  74  * Child/Parent (it can be in any process):
  75  *   (1) Call FileSystem API from content page with JS. Create a task and run.
  76  *   The base constructor [FileSystemTaskChildBase()] of the task should be
  77  *   called.
  78  *   (2) Forward the task to the parent process through the IPC and call
  79  *   [GetRequestParams] to prepare the parameters of the IPC.
  80  * Parent:
  81  *   (3) The parent process receives IPC and handle it in
  82  *   FileystemRequestParent. Get the IPC parameters and create a task to run the
  83  *   IPC task.
  84  *   (4) The task operation will be performed in the member function of
  85  * [IOWork]. A I/O  thread will be created to run that function. If error occurs
  86  *   during the operation, call [SetError] to record the error and then abort.
  87  *   (5) After finishing the task operation, call [HandleResult] to send the
  88  *   result back to the child process though the IPC.
  89  *   (6) Call [GetRequestResult] request result to prepare the parameters of the
  90  *   IPC. Because the formats of the error result for different task are the
  91  *   same, FileSystemTaskChildBase can handle the error message without
  92  *   interfering.
  93  *   Each task only needs to implement its specific success result preparation
  94  *   function -[GetSuccessRequestResult].
  95  * Child/Parent:
  96  *   (7) The process receives IPC and calls [SetRequestResult] to get the
  97  *   task result. Each task needs to implement its specific success result
  98  *   parsing function [SetSuccessRequestResult] to get the success result.
  99  *   (8) Call [HandlerCallback] to send the task result to the content page.
 100  */
 101 class FileSystemTaskChildBase : public PFileSystemRequestChild {
 102   friend class PFileSystemRequestChild;
 103
 104  public:
 105   NS_INLINE_DECL_REFCOUNTING(FileSystemTaskChildBase, final)
 106
 107   /*
 108    * Start the task. It will dispatch all the information to the parent process,
 109    * PBackground thread. This method must be called from the owning thread.
 110    */
 111   void Start();
 112
 113   /*
 114    * The error codes are defined in xpcom/base/ErrorList.h and their
 115    * corresponding error name and message are defined in dom/base/domerr.msg.
 116    */
 117   void SetError(const nsresult& aErrorCode);
 118
 119   FileSystemBase* GetFileSystem() const;
 120
 121   /*
 122    * After the task is completed, this function will be called to pass the task
 123    * result to the content page. This method is called in the owning thread.
 124    * Override this function to handle the call back to the content page.
 125    */
 126   virtual void HandlerCallback() = 0;
 127
 128   bool HasError() const { return NS_FAILED(mErrorValue); }
 129
 130  protected:
 131   /*
 132    * To create a task to handle the page content request.
 133    */
 134   FileSystemTaskChildBase(nsIGlobalObject* aGlobalObject,
 135                           FileSystemBase* aFileSystem);
 136
 137   virtual ~FileSystemTaskChildBase();
 138
 139   /*
 140    * Wrap the task parameter to FileSystemParams for sending it through IPC.
 141    * It will be called when we need to forward a task from the child process to
 142    * the parent process. This method runs in the owning thread.
 143    * @param filesystem The string representation of the file system.
 144    */
 145   virtual FileSystemParams GetRequestParams(const nsString& aSerializedDOMPath,
 146                                             ErrorResult& aRv) const = 0;
 147
 148   /*
 149    * Unwrap the IPC message to get the task success result.
 150    * It will be called when the task is completed successfully and an IPC
 151    * message is received in the child process and we want to get the task
 152    * success result. This method runs in the owning thread.
 153    */
 154   virtual void SetSuccessRequestResult(const FileSystemResponseValue& aValue,
 155                                        ErrorResult& aRv) = 0;
 156
 157   // Overrides PFileSystemRequestChild
 158   virtual mozilla::ipc::IPCResult Recv__delete__(
 159       const FileSystemResponseValue& value) final;
 160
 161   nsresult mErrorValue;
 162   RefPtr<FileSystemBase> mFileSystem;
 163   nsCOMPtr<nsIGlobalObject> mGlobalObject;
 164
 165  private:
 166   /*
 167    * Unwrap the IPC message to get the task result.
 168    * It will be called when the task is completed and an IPC message is received
 169    * in the content process and we want to get the task result. This runs on the
 170    * owning thread.
 171    */
 172   void SetRequestResult(const FileSystemResponseValue& aValue);
 173 };
 174
 175 // This class is the 'alter ego' of FileSystemTaskChildBase in the PBackground
 176 // world.
 177 class FileSystemTaskParentBase : public Runnable {
 178  public:
 179   FileSystemTaskParentBase()
 180       : Runnable("FileSystemTaskParentBase"),
 181         mErrorValue(NS_ERROR_NOT_INITIALIZED) {}
 182
 183   /*
 184    * Start the task. This must be called from the PBackground thread only.
 185    */
 186   void Start();
 187
 188   /*
 189    * The error codes are defined in xpcom/base/ErrorList.h and their
 190    * corresponding error name and message are defined in dom/base/domerr.msg.
 191    */
 192   void SetError(const nsresult& aErrorCode);
 193
 194   /*
 195    * The function to perform task operation. It will be run on the I/O
 196    * thread of the parent process.
 197    * Overrides this function to define the task operation for individual task.
 198    */
 199   virtual nsresult IOWork() = 0;
 200
 201   /*
 202    * Wrap the task success result to FileSystemResponseValue for sending it
 203    * through IPC. This method runs in the PBackground thread.
 204    * It will be called when the task is completed successfully and we need to
 205    * send the task success result back to the child process.
 206    */
 207   virtual FileSystemResponseValue GetSuccessRequestResult(
 208       ErrorResult& aRv) const = 0;
 209
 210   /*
 211    * After finishing the task operation, handle the task result.
 212    * If it is an IPC task, send back the IPC result. It runs on the PBackground
 213    * thread.
 214    */
 215   void HandleResult();
 216
 217   bool HasError() const { return NS_FAILED(mErrorValue); }
 218
 219   NS_IMETHOD
 220   Run() override;
 221
 222   virtual nsresult GetTargetPath(nsAString& aPath) const = 0;
 223
 224  private:
 225   /*
 226    * Wrap the task result to FileSystemResponseValue for sending it through IPC.
 227    * It will be called when the task is completed and we need to
 228    * send the task result back to the content. This runs on the PBackground
 229    * thread.
 230    */
 231   FileSystemResponseValue GetRequestResult() const;
 232
 233  protected:
 234   /*
 235    * To create a parent process task delivered from the child process through
 236    * IPC.
 237    */
 238   FileSystemTaskParentBase(FileSystemBase* aFileSystem,
 239                            const FileSystemParams& aParam,
 240                            FileSystemRequestParent* aParent);
 241
 242   virtual ~FileSystemTaskParentBase();
 243
 244   nsresult mErrorValue;
 245   RefPtr<FileSystemBase> mFileSystem;
 246   RefPtr<FileSystemRequestParent> mRequestParent;
 247   nsCOMPtr<nsIEventTarget> mBackgroundEventTarget;
 248 };
 249
 250 }  // namespace dom
 251 }  // namespace mozilla
 252
 253 #endif  // mozilla_dom_FileSystemTaskBase_h