Correct threading documentation example.

docs/design/threading.md

Index: docs/design/threading.md
diff --git a/docs/design/threading.md b/docs/design/threading.md
index 105891cfab01b4c9e07c8fe9e78f826b46549d55..9faa6d0cb9e2cee83781f296a72e587d5818a152 100644
--- a/docs/design/threading.md
+++ b/docs/design/threading.md
@@ -19,7 +19,7 @@ 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#).
 
@@ -242,18 +242,22 @@ raw pointer with `make_scoped_refptr()`:
      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) {
         ...
       }