summaryrefslogtreecommitdiffstats
path: root/dom/filesystem/FileSystemTaskBase.h
diff options
context:
space:
mode:
authorMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
committerMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
commit5f8de423f190bbb79a62f804151bc24824fa32d8 (patch)
tree10027f336435511475e392454359edea8e25895d /dom/filesystem/FileSystemTaskBase.h
parent49ee0794b5d912db1f95dce6eb52d781dc210db5 (diff)
downloadUXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.gz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.lz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.xz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.zip
Add m-esr52 at 52.6.0
Diffstat (limited to 'dom/filesystem/FileSystemTaskBase.h')
-rw-r--r--dom/filesystem/FileSystemTaskBase.h279
1 files changed, 279 insertions, 0 deletions
diff --git a/dom/filesystem/FileSystemTaskBase.h b/dom/filesystem/FileSystemTaskBase.h
new file mode 100644
index 000000000..9910f4c1f
--- /dev/null
+++ b/dom/filesystem/FileSystemTaskBase.h
@@ -0,0 +1,279 @@
+/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* vim: set ts=8 sts=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 "nsIIPCBackgroundChildCreateCallback.h"
+#include "nsThreadUtils.h"
+
+namespace mozilla {
+namespace dom {
+
+class BlobImpl;
+class FileSystemBase;
+class FileSystemParams;
+class PBlobParent;
+
+/*
+ * The base class to implement a Task class.
+ * The file system operations can only be performed in the parent process. In
+ * order to avoid duplicated code, we used PBackground for child-parent and
+ * parent-parent communications.
+ *
+ * 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 any process loading content, while
+ * the right block is the call sequence only inside the parent process.
+ *
+ * Page
+ * |
+ * | (1)
+ * ______|_________________________ | _________________________________
+ * | | | | | |
+ * | | | | | |
+ * | V | IPC | PBackground thread on |
+ * | [new FileSystemTaskChildBase()] | | | the parent process |
+ * | | | | | |
+ * | | (2) | | |
+ * | V | (3) | |
+ * | [GetRequestParams]------------------->[new FileSystemTaskParentBase()] |
+ * | | | | |
+ * | | | | | (4) _____________ |
+ * | | | | | | | |
+ * | | | | | | I/O Thread | |
+ * | | | | | | | |
+ * | | | | ---------> [IOWork] | |
+ * | | IPC | | | | |
+ * | | | | | | (5) | |
+ * | | | | -------------- | |
+ * | | | | | |_____________| |
+ * | | | | | |
+ * | | | | V |
+ * | | | | [HandleResult] |
+ * | | | | | |
+ * | | | | (6) |
+ * | | (7) | V |
+ * | [SetRequestResult]<---------------------[GetRequestResult] |
+ * | | | | |
+ * | | (8) | | | |
+ * | V | | | |
+ * |[HandlerCallback] | IPC | |
+ * |_______|_________________________| | |_________________________________|
+ * | |
+ * V
+ * Page
+ *
+ * 1. From the process that is handling the request
+ * Child/Parent (it can be in any process):
+ * (1) Call FileSystem API from content page with JS. Create a task and run.
+ * The base constructor [FileSystemTaskChildBase()] 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.
+ * (4) The task operation will be performed in the member function of [IOWork].
+ * A I/O 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, FileSystemTaskChildBase can handle the error message without
+ * interfering.
+ * Each task only needs to implement its specific success result preparation
+ * function -[GetSuccessRequestResult].
+ * Child/Parent:
+ * (7) The 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.
+ */
+class FileSystemTaskChildBase : public PFileSystemRequestChild
+ , public nsIIPCBackgroundChildCreateCallback
+{
+public:
+ NS_DECL_ISUPPORTS
+ NS_DECL_NSIIPCBACKGROUNDCHILDCREATECALLBACK
+
+ /*
+ * Start the task. It will dispatch all the information to the parent process,
+ * PBackground thread. This method must be called from the owning thread.
+ */
+ 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;
+
+ /*
+ * After the task is completed, this function will be called to pass the task
+ * result to the content page. This method is called in the owning thread.
+ * Override this function to handle the call back to the content page.
+ */
+ virtual void
+ HandlerCallback() = 0;
+
+ bool
+ HasError() const { return NS_FAILED(mErrorValue); }
+
+protected:
+ /*
+ * To create a task to handle the page content request.
+ */
+ explicit FileSystemTaskChildBase(FileSystemBase* aFileSystem);
+
+ virtual
+ ~FileSystemTaskChildBase();
+
+ /*
+ * 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 parent process. This method runs in the owning thread.
+ * @param filesystem The string representation of the file system.
+ */
+ virtual FileSystemParams
+ GetRequestParams(const nsString& aSerializedDOMPath,
+ ErrorResult& aRv) 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. This method runs in the owning thread.
+ */
+ virtual void
+ SetSuccessRequestResult(const FileSystemResponseValue& aValue,
+ ErrorResult& aRv) = 0;
+
+ // Overrides PFileSystemRequestChild
+ virtual bool
+ Recv__delete__(const FileSystemResponseValue& value) override;
+
+ nsresult mErrorValue;
+ RefPtr<FileSystemBase> mFileSystem;
+
+private:
+
+ /*
+ * 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 content process and we want to get the task result. This runs on the
+ * owning thread.
+ */
+ void
+ SetRequestResult(const FileSystemResponseValue& aValue);
+};
+
+// This class is the 'alter ego' of FileSystemTaskChildBase in the PBackground
+// world.
+class FileSystemTaskParentBase : public Runnable
+{
+public:
+ /*
+ * Start the task. This must be called from the PBackground thread only.
+ */
+ 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);
+
+ /*
+ * The function to perform task operation. It will be run on the I/O
+ * thread of the parent process.
+ * Overrides this function to define the task operation for individual task.
+ */
+ virtual nsresult
+ IOWork() = 0;
+
+ /*
+ * Wrap the task success result to FileSystemResponseValue for sending it
+ * through IPC. This method runs in the PBackground thread.
+ * 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(ErrorResult& aRv) const = 0;
+
+ /*
+ * After finishing the task operation, handle the task result.
+ * If it is an IPC task, send back the IPC result. It runs on the PBackground
+ * thread.
+ */
+ void
+ HandleResult();
+
+ // If this task must do something on the main-thread before IOWork(), it must
+ // overwrite this method. Otherwise it returns true if the FileSystem must be
+ // initialized on the main-thread. It's called from the Background thread.
+ virtual bool
+ NeedToGoToMainThread() const;
+
+ // This method is called only if NeedToGoToMainThread() returns true.
+ // Of course, it runs on the main-thread.
+ virtual nsresult
+ MainThreadWork();
+
+ bool
+ HasError() const { return NS_FAILED(mErrorValue); }
+
+ NS_IMETHOD
+ Run() override;
+
+ virtual nsresult
+ GetTargetPath(nsAString& aPath) const = 0;
+
+private:
+ /*
+ * 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 content. This runs on the PBackground
+ * thread.
+ */
+ FileSystemResponseValue
+ GetRequestResult() const;
+
+protected:
+ /*
+ * To create a parent process task delivered from the child process through
+ * IPC.
+ */
+ FileSystemTaskParentBase(FileSystemBase* aFileSystem,
+ const FileSystemParams& aParam,
+ FileSystemRequestParent* aParent);
+
+ virtual
+ ~FileSystemTaskParentBase();
+
+ nsresult mErrorValue;
+ RefPtr<FileSystemBase> mFileSystem;
+ RefPtr<FileSystemRequestParent> mRequestParent;
+ nsCOMPtr<nsIEventTarget> mBackgroundEventTarget;
+};
+
+} // namespace dom
+} // namespace mozilla
+
+#endif // mozilla_dom_FileSystemTaskBase_h