Index: docs/design/threading.md |
diff --git a/docs/design/threading.md b/docs/design/threading.md |
new file mode 100644 |
index 0000000000000000000000000000000000000000..105891cfab01b4c9e07c8fe9e78f826b46549d55 |
--- /dev/null |
+++ b/docs/design/threading.md |
@@ -0,0 +1,496 @@ |
+# Threading |
+ |
+[TOC] |
+ |
+## Overview |
+ |
+Chromium is a very multithreaded product. We try to keep the UI as responsive as |
+possible, and this means not blocking the UI thread with any blocking I/O or |
+other expensive operations. Our approach is to use message passing as the way of |
+communicating between threads. We discourage locking and threadsafe |
+objects. Instead, objects live on only one thread, we pass messages between |
+threads for communication, and we use callback interfaces (implemented by |
+message passing) for most cross-thread requests. |
+ |
+The `Thread` object is defined in |
+[`base/threading/thread.h`](https://cs.chromium.org/chromium/src/base/threading/thread.h). |
+In general you should probably use one of the existing threads described below |
+rather than make new ones. We already have a lot of threads that are difficult |
+to keep track of. Each thread has a `MessageLoop` (see |
+[`base/message_loop/message_loop.h`](https://cs.chromium.org/chromium/src/base/message_loop/message_loop.h) |
+that processes messages for that thread. You can get the message loop for a |
+thread using the `Thread.message_loop()` function. More details about |
+`MessageLoop` can be found in |
+[Anatomy of Chromium MessageLoop](https://docs.google.com/document/d/1_pJUHO3f3VyRSQjEhKVvUU7NzCyuTCQshZvbWeQiCXU/view#). |
+ |
+## Existing threads |
+ |
+Most threads are managed by the BrowserProcess object, which acts as the service |
+manager for the main "browser" process. By default, everything happens on the UI |
+thread. We have pushed certain classes of processing into these other |
+threads. It has getters for the following threads: |
+ |
+* **ui_thread**: Main thread where the application starts up. |
+* **io_thread**: This thread is somewhat mis-named. It is the dispatcher thread |
+ that handles communication between the browser process and all the |
+ sub-processes. It is also where all resource requests (web page loads) are |
+ dispatched from (see |
+ [Multi-process Architecture](https://www.chromium.org/developers/design-documents/multi-process-architecture)). |
+* **file_thread**: A general process thread for file operations. When you want to |
+ do blocking filesystem operations (for example, requesting an icon for a file |
+ type, or writing downloaded files to disk), dispatch to this thread. |
+* **db_thread**: A thread for database operations. For example, the cookie |
+ service does sqlite operations on this thread. Note that the history database |
+ doesn't use this thread yet. |
+* **safe_browsing_thread** |
+ |
+Several components have their own threads: |
+ |
+* **History**: The history service object has its own thread. This might be |
+ merged with the db_thread above. However, we need to be sure that things |
+ happen in the correct order -- for example, that cookies are loaded before |
+ history since cookies are needed for the first load, and history |
+ initialization is long and will block it. |
+* **Proxy service**: See |
+ [`net/http/http_proxy_service.cc`](https://cs.chromium.org/chromium/src/net/http/http_proxy_service.cc). |
+* **Automation proxy**: This thread is used to communicate with the UI test |
+ program driving the app. |
+ |
+## Keeping the browser responsive |
+ |
+As hinted in the overview, we avoid doing any blocking I/O on the UI thread to |
+keep the UI responsive. Less apparent is that we also need to avoid blocking |
+I/O on the IO thread. The reason is that if we block it for an expensive |
+operation, say disk access, then IPC messages don't get processed. The effect |
+is that the user can't interact with a page. Note that asynchronous/overlapped |
+I/O are fine. |
+ |
+Another thing to watch out for is to not block threads on one another. Locks |
+should only be used to swap in a shared data structure that can be accessed on |
+multiple threads. If one thread updates it based on expensive computation or |
+through disk access, then that slow work should be done without holding on to |
+the lock. Only when the result is available should the lock be used to swap in |
+the new data. An example of this is in PluginList::LoadPlugins |
+([`content/common/plugin_list.cc`](https://cs.chromium.org/chromium/src/content/common/plugin_list.cc). If |
+you must use locks, |
+[here](https://www.chromium.org/developers/lock-and-condition-variable) |
+are some best practices and pitfalls to avoid. |
+ |
+In order to write non-blocking code, many APIs in Chromium are |
+asynchronous. Usually this means that they either need to be executed on a |
+particular thread and will return results via a custom delegate interface, or |
+they take a `base::Callback<>` object that is called when the requested |
+operation is completed. Executing work on a specific thread is covered in the |
+PostTask section below. |
+ |
+## Getting stuff to other threads |
+ |
+### `base::Callback<>`, Async APIs and Currying |
+ |
+ |
+A `base::Callback<>` (see the docs in |
+[`base/callback.h`](https://cs.chromium.org/chromium/src/base/callback.h) is |
+a templated class with a `Run()` method. It is a generalization of a function |
+pointer and is created by a call to `base::Bind`. Async APIs often will take a |
+`base::Callback<>` as a means to asynchronously return the results of an |
+operation. Here is an example of a hypothetical FileRead API. |
+ |
+ void ReadToString(const std::string& filename, const base::Callback<void(const std::string&)>& on_read); |
+ |
+ void DisplayString(const std::string& result) { |
+ LOG(INFO) << result; |
+ } |
+ |
+ void SomeFunc(const std::string& file) { |
+ ReadToString(file, base::Bind(&DisplayString)); |
+ }; |
+ |
+In the example above, `base::Bind` takes the function pointer `&DisplayString` |
+and turns it into a `base::Callback<void(const std::string& result)>`. The type |
+of the generated `base::Callback<>` is inferred from the arguments. Why not |
+just pass the function pointer directly? The reason is `base::Bind` allows the |
+caller to adapt function interfaces and/or attach extra context |
+via [Currying](http://en.wikipedia.org/wiki/Currying). For instance, if we had |
+a utility function `DisplayStringWithPrefix` that took an extra argument with |
+the prefix, we use `base::Bind` to adapt the interface as follows. |
+ |
+ void DisplayStringWithPrefix(const std::string& prefix, const std::string& result) { |
+ LOG(INFO) << prefix << result; |
+ } |
+ |
+ void AnotherFunc(const std::string& file) { |
+ ReadToString(file, base::Bind(&DisplayStringWithPrefix, "MyPrefix: ")); |
+ }; |
+ |
+This can be used in lieu of creating an adapter functions a small classes that |
+holds prefix as a member variable. Notice also that the `"MyPrefix: "` argument |
+is actually a `const char*`, while `DisplayStringWithPrefix` actually wants a |
+`const std::string&`. Like normal function dispatch, `base::Bind`, will coerce |
+parameters types if possible. |
+ |
+See [How arguments are handled by base::Bind()](#how_arguments_are_handled) |
+below for more details about argument storage, copying, and special handling of |
+references. |
+ |
+### PostTask |
+ |
+The lowest level of dispatching to another thread is to use the |
+`MessageLoop.PostTask` and `MessageLoop.PostDelayedTask` |
+(see |
+[`base/message_loop/message_loop.h`](https://cs.chromium.org/chromium/src/base/message_loop/message_loop.h)). |
+PostTask schedules a task to be run on a particular thread. A task is defined |
+as a `base::Closure`, which is a typedef for a |
+`base::Callback<void(void)>`. `PostDelayedTask` schedules a task to be run after |
+a delay on a particular thread. A task is represented by the `base::Closure` |
+typedef, which contains a `Run()` function, and is created by calling |
+`base::Bind()`. To process a task, the message loop eventually calls |
+`base::Closure`'s `Run` function, and then drops the reference to the task |
+object. Both `PostTask` and `PostDelayedTask` take a `tracked_objects::Location` |
+parameter, which is used for lightweight debugging purposes (counts and |
+primitive profiling of pending and completed tasks can be monitored in a debug |
+build via the url about:objects). Generally the macro value `FROM_HERE` is the |
+appropriate value to use in this parameter. |
+ |
+Note that new tasks go on the message loop's queue, and any delay that is |
+specified is subject to the operating system's timer resolutions. This means |
+that under Windows, very small timeouts (under 10ms) will likely not be honored |
+(and will be longer). Using a timeout of 0 in `PostDelayedTask` is equivalent to |
+calling `PostTask`, and adds no delay beyond queuing delay. `PostTask` is also |
+used to do something on the current thread "sometime after the current |
+processing returns to the message loop." Such a continuation on the current |
+thread can be used to assure that other time critical tasks are not starved on |
+this thread. |
+ |
+The following is an example of a creating a task for a function and posting it |
+to another thread (in this example, the file thread): |
+ |
+ void WriteToFile(const std::string& filename, const std::string& data); |
+ BrowserThread::PostTask(BrowserThread::FILE, FROM_HERE, |
+ base::Bind(&WriteToFile, "foo.txt", "hello world!")); |
+ |
+You should always use `BrowserThread` to post tasks between threads. Never |
+cache `MessageLoop` pointers as it can cause bugs such as the pointers being |
+deleted while you're still holding on to them. More information can be |
+found |
+[here](https://www.chromium.org/developers/design-documents/threading/suble-threading-bugs-and-patterns-to-avoid-them). |
+ |
+ |
+### base::Bind() and class methods. |
+ |
+The `base::Bind()` API also supports invoking class methods as well. The syntax |
+is very similar to calling `base::Bind()` on a function, except the first |
+argument should be the object the method belongs to. By default, the object that |
+`PostTask` uses must be a thread-safe reference-counted object. Reference |
+counting ensures that the object invoked on another thread will stay alive until |
+the task completes. |
+ |
+ class MyObject : public base::RefCountedThreadSafe<MyObject> { |
+ public: |
+ void DoSomething(const std::string16& name) { |
+ thread_->message_loop()->PostTask( |
+ FROM_HERE, base::Bind(&MyObject::DoSomethingOnAnotherThread, this, name)); |
+ } |
+ |
+ void DoSomethingOnAnotherThread(const std::string16& name) { |
+ ... |
+ } |
+ private: |
+ // Always good form to make the destructor private so that only RefCounted |
+ // ThreadSafe can access it. |
+ // This avoids bugs with double deletes. |
+ friend class base::RefCountedThreadSafe<MyObject>; |
+ |
+ ~MyObject(); |
+ Thread* thread_; |
+ }; |
+ |
+If you have external synchronization structures that can completely ensure that |
+an object will always be alive while the task is waiting to execute, you can |
+wrap the object pointer with `base::Unretained()` when calling `base::Bind()` to |
+disable the refcounting. This will also allow using `base::Bind()` on classes |
+that are not refcounted. Be careful when doing this! |
+ |
+ |
+ |
+### How arguments are handled by `base::Bind()` |
+<a id="how_arguments_are_handled"></a> |
+ |
+The arguments given to `base::Bind()` are copied into an internal |
+`InvokerStorage` structure object (defined in |
+[`base/bind_internal.h`](http://cs.chromium.org/chromium/src/base/bind_internal.h). |
+When the function is finally executed, it will see copies of the arguments. This is important if your target function or method takes a const reference; the |
+reference will be to a copy of the argument. If you need a reference to the |
+original argument, you can wrap the argument with `base::ConstRef()`. Use this |
+carefully as it is likely dangerous if target of the reference cannot be |
+guaranteed to live past when the task is executed. In particular, it is almost |
+never safe to use `base::ConstRef()` to a variable on the stack unless you can |
+guarantee the stack frame will not be invalidated until the asynchronous task |
+finishes. |
+ |
+Sometimes, you will want to pass reference-counted objects as parameters (be |
+sure to use `RefCountedThreadSafe` and not plain `RefCounted` as the base class |
+for these objects). To ensure that the object lives throughout the entire |
+request, the Closure generated by `base::Bind` must keep a reference to it. This |
+can be done by passing scoped_refptr as the parameter type, or by wrapping the |
+raw pointer with `make_scoped_refptr()`: |
+ |
+ class SomeParamObject : public base::RefCountedThreadSafe<SomeParamObject> { |
+ ... |
+ }; |
+ |
+ class MyObject : public base::RefCountedThreadSafe<MyObject> { |
+ public: |
+ void DoSomething() { |
+ scoped_refptr<SomeParamObject> param(new SomeParamObject); |
+ thread_->message_loop()->PostTask(FROM_HERE |
+ base::Bind(&MyObject::DoSomethingOnAnotherThread, this, param)); |
+ } |
+ void DoSomething2() { |
+ SomeParamObject* param = new SomeParamObject; |
+ thread_->message_loop()->PostTask(FROM_HERE |
+ base::Bind(&MyObject::DoSomethingOnAnotherThread, this, |
+ make_scoped_refptr(param))); |
+ } |
+ // Note how this takes a raw pointer. The important part is that |
+ // base::Bind() was passed a scoped_refptr; using a scoped_refptr |
+ // here would result in an extra AddRef()/Release() pair. |
+ void DoSomethingOnAnotherThread(SomeParamObject* param) { |
+ ... |
+ } |
+ }; |
+ |
+If you want to pass the object without taking a reference on it, wrap the |
+argument with `base::Unretained()`. Again, using this means there are external |
+guarantees on the lifetime of the object, so tread carefully! |
+ |
+If your object has a non-trivial destructor that needs to run on a specific |
+thread, you can use the following trait. This is needed since timing races could |
+lead to a task completing execution before the code that posted it has unwound |
+the stack. |
+ |
+ class MyObject : public base::RefCountedThreadSafe<MyObject, BrowserThread::DeleteOnIOThread> { |
+ |
+## Callback cancellation |
+ |
+There are 2 major reasons to cancel a task (in the form of a Callback): |
+* You want to do something later on your object, but at the time your callback |
+ runs, your object may have been destroyed. |
+* When input changes (e.g. user input), old tasks become unnecessary. For |
+ performance considerations, you should cancel them. |
+See following about different approaches for cancellation. |
+ |
+### Important notes about cancellation |
+ |
+It's dangerous to cancel a task with owned parameters. See the following |
+example. (The example uses `base::WeakPtr` for cancellation, but the problem |
+applies to all approaches). |
+ |
+ class MyClass { |
+ public: |
+ // Owns |p|. |
+ void DoSomething(AnotherClass* p) { |
+ ... |
+ } |
+ WeakPtr<MyClass> AsWeakPtr() { |
+ return weak_factory_.GetWeakPtr(); |
+ } |
+ private: |
+ base::WeakPtrFactory<MyClass> weak_factory_; |
+ }; |
+ |
+ ... |
+ Closure cancelable_closure = Bind(&MyClass::DoSomething, object->AsWeakPtr(), p); |
+ Callback<void(AnotherClass*)> cancelable_callback = Bind(&MyClass::DoSomething, object->AsWeakPtr()); |
+ ... |
+ |
+ void FunctionRunLater(const Closure& cancelable_closure, |
+ const Callback<void(AnotherClass*)>& cancelable_callback) { |
+ ... |
+ // Leak memory! |
+ cancelable_closure.Run(); |
+ cancelable_callback.Run(p); |
+ } |
+ |
+In `FunctionRunLater`, both `Run()` calls will leak `p` when object is already |
+destructed. Using `scoped_ptr` can fix the bug: |
+ |
+ class MyClass { |
+ public: |
+ void DoSomething(scoped_ptr<AnotherClass> p) { |
+ ... |
+ } |
+ ... |
+ }; |
+ |
+### base::WeakPtr and Cancellation __[NOT THREAD SAFE]__ |
+ |
+You can use a `base::WeakPtr` and `base::WeakPtrFactory` |
+(in |
+[base/memory/weak_ptr.h](https://cs.chromium.org/chromium/src/base/memory/weak_ptr.h)) |
+to ensure that any invokes can not outlive the object they are being invoked on, |
+without using reference counting. The `base::Bind` mechanism has special |
+understanding for `base::WeakPtr` that will disable the task's execution if the |
+`base::WeakPtr` has been invalidated. The `base::WeakPtrFactory` object can be |
+used to generate `base::WeakPtr` instances that know about the factory |
+object. When the factory is destroyed, all the `base::WeakPtr` will have their |
+internal "invalidated" flag set, which will make any tasks bound to them to not |
+dispatch. By putting the factory as a member of the object being dispatched to, |
+you can get automatic cancellation. |
+ |
+__NOTE__: This only works when the task is posted to the same thread. Currently |
+there is not a general solution that works for tasks posted to other |
+threads. See |
+the [next section about CancelableTaskTracker](#cancelable_task_tracker) for an |
+alternative solution. |
+ |
+ class MyObject { |
+ public: |
+ MyObject() : weak_factory_(this) {} |
+ |
+ void DoSomething() { |
+ const int kDelayMS = 100; |
+ MessageLoop::current()->PostDelayedTask(FROM_HERE, |
+ base::Bind(&MyObject::DoSomethingLater, weak_factory_.GetWeakPtr()), |
+ kDelayMS); |
+ } |
+ |
+ void DoSomethingLater() { |
+ ... |
+ } |
+ |
+ private: |
+ base::WeakPtrFactory<MyObject> weak_factory_; |
+ }; |
+ |
+### CancelableTaskTracker |
+<a id="cancelable_task_tracker"></a> |
+ |
+While `base::WeakPtr` is very helpful to cancel a task, it is not thread safe so |
+can not be used to cancel tasks running on another thread. This is sometimes a |
+performance critical requirement. E.g. We need to cancel database lookup task on |
+DB thread when user changes inputed text. In this kind of situation |
+`CancelableTaskTracker` is appropriate. |
+ |
+With `CancelableTaskTracker` you can cancel a single task with returned |
+`TaskId`. This is another reason to use `CancelableTaskTracker` instead of |
+`base::WeakPtr`, even in a single thread context. |
+ |
+`CancelableTaskTracker` has 2 `Post` methods doing the same thing as the ones in |
+`base::TaskRunner`, with additional cancellation support. |
+ |
+ class UserInputHandler : public base::RefCountedThreadSafe<UserInputHandler> { |
+ // Runs on UI thread. |
+ void OnUserInput(Input input) { |
+ CancelPreviousTask(); |
+ DBResult* result = new DBResult(); |
+ task_id_ = tracker_->PostTaskAndReply( |
+ BrowserThread::GetMessageLoopProxyForThread(BrowserThread::DB).get(), |
+ FROM_HERE, |
+ base::Bind(&LookupHistoryOnDBThread, this, input, result), |
+ base::Bind(&ShowHistoryOnUIThread, this, base::Owned(result))); |
+ } |
+ |
+ void CancelPreviousTask() { |
+ tracker_->TryCancel(task_id_); |
+ } |
+ |
+ ... |
+ |
+ private: |
+ CancelableTaskTracker tracker_; // Cancels all pending tasks while destruction. |
+ CancelableTaskTracker::TaskId task_id_; |
+ ... |
+ }; |
+ |
+Since task runs on other threads, there's no guarantee it can be successfully |
+canceled. |
+ |
+When `TryCancel()` is called: |
+ |
+* If neither task nor reply has started running, both will be canceled. |
+* If task is already running or has finished running, reply will be canceled. |
+* If reply is running or has finished running, cancelation is a noop. |
+ |
+Like `base::WeakPtrFactory`, `CancelableTaskTracker` will cancel all tasks on |
+destruction. |
+ |
+### Cancelable request __(DEPRECATED)__ |
+ |
+Note. Cancelable request is deprecated. Please do not use it in new code. For |
+canceling tasks running on the same thread, use WeakPtr. For canceling tasks |
+running on a different thread, use `CancelableTaskTracker`. |
+ |
+A cancelable request makes it easier to make requests to another thread with |
+that thread returning some data to you asynchronously. Like the revokable store |
+system, it uses objects that track whether the originating object is alive. When |
+the calling object is deleted, the request will be canceled to prevent invalid |
+callbacks. |
+ |
+Like the revokable store system, a user of a cancelable request has |
+an object (here, called a _Consumer_) that tracks whether it is alive and will |
+auto-cancel any outstanding requests on deleting. |
+ |
+ class MyClass { |
+ void MakeRequest() { |
+ frontend_service->StartRequest(some_input1, some_input2, this, |
+ // Use base::Unretained(this) if this may cause a refcount cycle. |
+ base::Bind(&MyClass:RequestComplete, this)); |
+ } |
+ void RequestComplete(int status) { |
+ ... |
+ } |
+ |
+ private: |
+ CancelableRequestConsumer consumer_; |
+ }; |
+ |
+Note that the `MyClass::RequestComplete`, is bounded with |
+`base::Unretained(this)` here. |
+ |
+The consumer also allows you to associate extra data with a request. Use |
+`CancelableRequestConsumer` which will allow you to associate arbitrary data |
+with the handle returned by the provider service when you invoke the |
+request. The data will be automatically destroyed when the request is canceled. |
+ |
+A service handling requests inherits from `CancelableRequestProvider`. This |
+object provides methods for canceling in-flight requests, and will work with the |
+consumers to make sure everything is cleaned up properly on cancel. This |
+frontend service just tracks the request and sends it to a backend service on |
+another thread for actual processing. It would look like this: |
+ |
+ class FrontendService : public CancelableRequestProvider { |
+ typedef base::Callback<void(int)> RequestCallbackType; |
+ |
+ Handle StartRequest(int some_input1, int some_input2, |
+ CallbackConsumer* consumer, |
+ const RequestCallbackType& callback) { |
+ scoped_refptr<CancelableRequest<FrontendService::RequestCallbackType>> |
+ request(new CancelableRequest(callback)); |
+ AddRequest(request, consumer); |
+ |
+ // Send the parameters and the request to the backend thread. |
+ backend_thread_->PostTask(FROM_HERE, |
+ base::Bind(&BackendService::DoRequest, backend_, request, |
+ some_input1, some_input2), 0); |
+ // The handle will have been set by AddRequest. |
+ return request->handle(); |
+ } |
+ }; |
+ |
+The backend service runs on another thread. It does processing and forwards the |
+result back to the original caller. It would look like this: |
+ |
+ class BackendService : public base::RefCountedThreadSafe<BackendService> { |
+ void DoRequest( |
+ scoped_refptr<CancelableRequest<FrontendService::RequestCallbackType>> |
+ request, |
+ int some_input1, int some_input2) { |
+ if (request->canceled()) |
+ return; |
+ |
+ ... do your processing ... |
+ |
+ // Execute ForwardResult() like you would do Run() on the base::Callback<>. |
+ request->ForwardResult(return_value); |
+ } |
+ }; |