Correct threading documentation example.

docs/design/threading.md

 # 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 
+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:
 
@@ skipping 202 matching lines @@
 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));
+
+        // Moving |param| prevents an extra AddRef()/Release() pair.

[lazyboy, 2017/06/23 20:43:27]

Nice, I think you should separate out this std::move tip, possibly to
DoSomething3, to keep things simple, then gradually advancing...

The simple example here is demonstrating how you could bind a function that
takes raw T* from scoped_refptr. And your change to RetainedRef by itself is
great/enough for the simpler case. The older code doesn't even compile, right?

[karandeepb, 2017/06/23 22:48:46]

Done. Yeah it doesn't compile.

+        thread_->message_loop()->PostTask(FROM_HERE,
+           base::Bind(&MyObject::DoSomethingOnAnotherThread, this,
+           base::RetainedRef(std::move(param))));
       }
       void DoSomething2() {
         SomeParamObject* param = new SomeParamObject;
-        thread_->message_loop()->PostTask(FROM_HERE
+        thread_->message_loop()->PostTask(FROM_HERE,
            base::Bind(&MyObject::DoSomethingOnAnotherThread, this,
-                             make_scoped_refptr(param)));
+                             base::RetainedRef(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.
+
+      // Note how this takes a raw pointer. The important part is that using

[lazyboy, 2017/06/23 20:43:27]

The comment here before was emphasizing that instead of using:
void DoSomethingOnAnotherThread(scoped_refptr<SomeParamObject> param),
i.e. using scoped_refptr<T> as argument would result in an additional
AddRef/Release vs a raw T* pointer argument. So I believe we should leave this
as is.

The mention of the requirement of RetainedRef should go to the callsites (i.e.
line 249 and 255), because regardless of saving AddRef/Release or not, it *is*
required to be able to use use T*

[karandeepb, 2017/06/23 22:48:46]

Done.

+      // base::RetainedRef allows passing a raw pointer when the callback is run
+      // preventing 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
@@ skipping 220 matching lines @@
           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);
       }
     };