Add NESTABLE_ASYNC APIs to Tracing

base/debug/trace_event.h

Index: base/debug/trace_event.h
diff --git a/base/debug/trace_event.h b/base/debug/trace_event.h
index f9dc1c94d6d65b885772a4b1bf3b16005c58c2e9..57a7f57b84773f64db2412bf72a012cee00a724b 100644
--- a/base/debug/trace_event.h
+++ b/base/debug/trace_event.h
@@ -530,6 +530,11 @@
 // only STEP_INTO or STEP_PAST macros; they can not mix and match. When the
 // operation completes, call ASYNC_END.
 //
+// ASYNC_STEP_INTO and ASYNC_STEP_PAST can only represent one level of phases,
+// between a pair of ASYNC_BEGIN and ASYNC_END. If an asynchronous operation
+// has multiple levels of nesting phases/events, ASYNC_NESTABLE_* APIs can be
+// used.
+//
 // An ASYNC trace typically occurs on a single thread (if not, they will only be
 // drawn on the thread defined in the ASYNC_BEGIN event), but all events in that
 // operation must use the same |name| and |id|. Each step can have its own
@@ -634,6 +639,47 @@
         static_cast<int>(base::PlatformThread::CurrentId()), \
         timestamp, TRACE_EVENT_FLAG_NONE)
 
+
+// Records a single ASYNC_NESTABLE_BEGIN event called "name" immediately, with 2
+// associated arguments. If the category is not enabled, then this
+// does nothing.
+// - category and name strings must have application lifetime (statics or
+//   literals). They may not include " chars.
+// - |id| is used to match the ASYNC_NESTABLE_BEGIN event with the
+//   ASYNC_NESTABLE_END event. Events are considered to match if their
+//   category_group, name and id values all match. |id| must either be a
+//   pointer or an integer value up to 64 bits. If it's a pointer, the bits
+//   will be xored with a hash of the process ID so that the same pointer on two
+//   different processes will not collide.
+// - Unmatched ASYNC_NESTABLE_END event will be parsed as an instant event,

[nduca, 2014/09/08 22:21:13]

Your docstrings here look like they're explaining the |id| argument. Can you
shuffle this around so its clear which is just explaining the general api vs the
arguments?

[xunjieli, 2014/09/09 13:31:18]

Done.

+//   and unmatched ASYNC_NESTABLE_BEGIN event will be parsed as an event, which
+//   starts at the time of the ASYNC_NESTABLE_BEGIN event and ends at the last
+//   ASYNC_NESTABLE_END event of that |id|.
+//
+//   ASYNC_NESTABLE_* APIs are used to capture asynchronous operations which can

[nduca, 2014/09/08 22:21:13]

this seems like its better up top of this comment block? think about good
comments:


One line sentence.

General explanation paragraph, usually provides information on when to use it,
what scenarios make sense.

Detail paragraphs. Here's where to put semantic information.

Argument information.

[xunjieli, 2014/09/09 13:31:19]

Done. Thanks for the detailed explanation!

+//   have multiple levels of nested events/phases. If an asynchronous operation
+//   only has one level of sub-events, one should consider using ASYNC_STEP_*.

[nduca, 2014/09/08 22:21:13]

I don't think we're intending people to point at async_step. We're probably
going to remove that, so I'd remove this If sentence.

[xunjieli, 2014/09/09 13:31:19]

Done.

+
+#define TRACE_EVENT_ASYNC_NESTABLE_BEGIN2(category_group, name, id, arg1_name, \
+        arg1_val, arg2_name, arg2_val) \
+    INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_NESTABLE_BEGIN, \
+        category_group, name, id, TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, \
+        arg2_name, arg2_val)
+// Records a single ASYNC_NESTABLE_END event for "name" immediately.
+// If the category is not enabled, then this does nothing.
+#define TRACE_EVENT_ASYNC_NESTABLE_END2(category_group, name, id, arg1_name, \
+        arg1_val, arg2_name, arg2_val) \
+    INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_NESTABLE_END, \
+        category_group, name, id, TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, \
+        arg2_name, arg2_val)
+// Records a single ASYNC_NESTABLE_INSTANT event for "name" immediately.
+// If the category is not enabled, then this does nothing.
+#define TRACE_EVENT_ASYNC_NESTABLE_INSTANT2(category_group, name, id, \
+        arg1_name, arg1_val, arg2_name, arg2_val) \
+    INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_NESTABLE_INSTANT, \
+        category_group, name, id, TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, \
+        arg2_name, arg2_val)
+
 // Records a single FLOW_BEGIN event called "name" immediately, with 0, 1 or 2
 // associated arguments. If the category is not enabled, then this
 // does nothing.
@@ -963,6 +1009,9 @@ TRACE_EVENT_API_CLASS_EXPORT extern \
 #define TRACE_EVENT_PHASE_ASYNC_STEP_INTO  ('T')
 #define TRACE_EVENT_PHASE_ASYNC_STEP_PAST  ('p')
 #define TRACE_EVENT_PHASE_ASYNC_END   ('F')
+#define TRACE_EVENT_PHASE_ASYNC_NESTABLE_BEGIN ('b')
+#define TRACE_EVENT_PHASE_ASYNC_NESTABLE_END ('e')
+#define TRACE_EVENT_PHASE_ASYNC_NESTABLE_INSTANT ('n')
 #define TRACE_EVENT_PHASE_FLOW_BEGIN ('s')
 #define TRACE_EVENT_PHASE_FLOW_STEP  ('t')
 #define TRACE_EVENT_PHASE_FLOW_END   ('f')