• file
• revisions
• annotate
• diff
• comparison
• raw

dom/filesystem/FileSystemTaskBase.h@b8a032363ba2 (annotated)

dom/filesystem/FileSystemTaskBase.h

Thu, 22 Jan 2015 13:21:57 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Thu, 22 Jan 2015 13:21:57 +0100

branch

TOR_BUG_9701

changeset 15

b8a032363ba2

permissions

-rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

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