gecko-dev/dom/filesystem/FileSystemTaskBase.h

/* -*- Mode: c++; c-basic-offset: 2; indent-tabs-mode: nil; tab-width: 40 -*- */
/* vim: set ts=2 et sw=2 tw=80: */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef mozilla_dom_FileSystemTaskBase_h
#define mozilla_dom_FileSystemTaskBase_h

#include "mozilla/ErrorResult.h"
#include "mozilla/dom/FileSystemRequestParent.h"
#include "mozilla/dom/PFileSystemRequestChild.h"
#include "mozilla/dom/ipc/Blob.h"

class nsIDOMFile;

namespace mozilla {
namespace dom {

class FileSystemBase;
class FileSystemParams;
class Promise;

/*
 * The base class to implement a Task class.
 * The task is used to handle the OOP (out of process) operations.
 * The file system operations can only be performed in the parent process. When
 * performing such a parent-process-only operation, a task will delivered the
 * operation to the parent process if needed.
 *
 * The following diagram illustrates the how a API call from the content page
 * starts a task and gets call back results.
 *
 * The left block is the call sequence inside the child process, while the
 * right block is the call sequence inside the parent process.
 *
 * There are two types of API call. One is from the content page of the child
 * process and we mark the steps as (1) to (8). The other is from the content
 * page of the parent process and we mark the steps as (1') to (4').
 *
 *       Page                                             Page
 *        |                                                |
 *        | (1)                                            |  (1')
 *  ______|________________     |     _____________________|_____________
 * |      |                |    |    |                     |             |
 * |      |  Task in       |    |    |  Task in            |             |
 * |      |  Child Process |    |    |  Parent Process     |             |
 * |      V                |   IPC   |                     V             |
 * [new FileSystemTaskBase()]   |    |     [new FileSystemTaskBase()]    |
 * |         |             |    |    |                         |         |
 * |         | (2)         |         |                         | (2')    |
 * |         V             |   (3)   |                         |         |
 * |    [GetRequestParams]------------->[new FileSystemTaskBase(...)]    |
 * |                       |         |          |              |         |
 * |                       |    |    |          | (4)          |         |
 * |                       |    |    |          |              V         |
 * |                       |    |    |          -----------> [Work]      |
 * |                       |   IPC   |                         |         |
 * |                       |    |    |                     (5) | (3')    |
 * |                       |    |    |                         V         |
 * |                       |    |    |          --------[HandleResult]   |
 * |                       |    |    |          |              |         |
 * |                       |         |          | (6)          |         |
 * |                       |   (7)   |          V              |         |
 * |   [SetRequestResult]<-------------[GetRequestResult]      |         |
 * |       |               |         |                         | (4')    |
 * |       | (8)           |    |    |                         |         |
 * |       V               |    |    |                         V         |
 * |[HandlerCallback]      |   IPC   |               [HandlerCallback]   |
 * |_______|_______________|    |    |_________________________|_________|
 *         |                    |                              |
 *         V                                                   V
 *        Page                                                Page
 *
 * 1. From child process page
 * Child:
 *   (1) Call FileSystem API from content page with JS. Create a task and run.
 *   The base constructor [FileSystemTaskBase()] of the task should be called.
 *   (2) Forward the task to the parent process through the IPC and call
 *   [GetRequestParams] to prepare the parameters of the IPC.
 * Parent:
 *   (3) The parent process receives IPC and handle it in
 *   FileystemRequestParent.
 *   Get the IPC parameters and create a task to run the IPC task. The base
 *   constructor [FileSystemTaskBase(aParam, aParent)] of the task should be
 *   called to set the task as an IPC task.
 *   (4) The task operation will be performed in the member function of [Work].
 *   A worker thread will be created to run that function. If error occurs
 *   during the operation, call [SetError] to record the error and then abort.
 *   (5) After finishing the task operation, call [HandleResult] to send the
 *   result back to the child process though the IPC.
 *   (6) Call [GetRequestResult] request result to prepare the parameters of the
 *   IPC. Because the formats of the error result for different task are the
 *   same, FileSystemTaskBase can handle the error message without interfering.
 *   Each task only needs to implement its specific success result preparation
 *   function -[GetSuccessRequestResult].
 * Child:
 *   (7) The child process receives IPC and calls [SetRequestResult] to get the
 *   task result. Each task needs to implement its specific success result
 *   parsing function [SetSuccessRequestResult] to get the success result.
 *   (8) Call [HandlerCallback] to send the task result to the content page.
 * 2. From parent process page
 * We don't need to send the task parameters and result to other process. So
 * there are less steps, but their functions are the same. The correspondence
 * between the two types of steps is:
 *   (1') = (1),
 *   (2') = (4),
 *   (3') = (5),
 *   (4') = (8).
 */
class FileSystemTaskBase
  : public nsRunnable
  , public PFileSystemRequestChild
{
public:
  /*
   * Start the task. If the task is running the child process, it will be
   * forwarded to parent process by IPC, or else, creates a worker thread to
   * do the task work.
   */
  void
  Start();

  /*
   * The error codes are defined in xpcom/base/ErrorList.h and their
   * corresponding error name and message are defined in dom/base/domerr.msg.
   */
  void
  SetError(const nsresult& aErrorCode);

  FileSystemBase*
  GetFileSystem() const;

  /*
   * Get the type of permission access required to perform this task.
   */
  virtual void
  GetPermissionAccessType(nsCString& aAccess) const = 0;

  NS_DECL_NSIRUNNABLE
protected:
  /*
   * To create a task to handle the page content request.
   */
  FileSystemTaskBase(FileSystemBase* aFileSystem);

  /*
   * To create a parent process task delivered from the child process through
   * IPC.
   */
  FileSystemTaskBase(FileSystemBase* aFileSystem,
                     const FileSystemParams& aParam,
                     FileSystemRequestParent* aParent);

  virtual
  ~FileSystemTaskBase();

  /*
   * The function to perform task operation. It will be run on the worker
   * thread of the parent process.
   * Overrides this function to define the task operation for individual task.
   */
  virtual nsresult
  Work() = 0;

  /*
   * After the task is completed, this function will be called to pass the task
   * result to the content page.
   * Override this function to handle the call back to the content page.
   */
  virtual void
  HandlerCallback() = 0;

  /*
   * Wrap the task parameter to FileSystemParams for sending it through IPC.
   * It will be called when we need to forward a task from the child process to
   * the prarent process.
   * @param filesystem The string representation of the file system.
   */
  virtual FileSystemParams
  GetRequestParams(const nsString& aFileSystem) const = 0;

  /*
   * Wrap the task success result to FileSystemResponseValue for sending it
   * through IPC.
   * It will be called when the task is completed successfully and we need to
   * send the task success result back to the child process.
   */
  virtual FileSystemResponseValue
  GetSuccessRequestResult() const = 0;

  /*
   * Unwrap the IPC message to get the task success result.
   * It will be called when the task is completed successfully and an IPC
   * message is received in the child process and we want to get the task
   * success result.
   */
  virtual void
  SetSuccessRequestResult(const FileSystemResponseValue& aValue) = 0;

  bool
  HasError() const { return mErrorValue != NS_OK; }

  // Overrides PFileSystemRequestChild
  virtual bool
  Recv__delete__(const FileSystemResponseValue& value) MOZ_OVERRIDE;

  BlobParent*
  GetBlobParent(nsIDOMFile* aFile) const;

  nsresult mErrorValue;

  nsRefPtr<FileSystemBase> mFileSystem;
  nsRefPtr<FileSystemRequestParent> mRequestParent;
private:
  /*
   * After finishing the task operation, handle the task result.
   * If it is an IPC task, send back the IPC result. Or else, send the result
   * to the content page.
   */
  void
  HandleResult();

  /*
   * Wrap the task result to FileSystemResponseValue for sending it through IPC.
   * It will be called when the task is completed and we need to
   * send the task result back to the child process.
   */
  FileSystemResponseValue
  GetRequestResult() const;

  /*
   * Unwrap the IPC message to get the task result.
   * It will be called when the task is completed and an IPC message is received
   * in the child process and we want to get the task result.
   */
  void
  SetRequestResult(const FileSystemResponseValue& aValue);
};

} // namespace dom
} // namespace mozilla

#endif // mozilla_dom_FileSystemTaskBase_h