Add NESTABLE_ASYNC APIs to Tracing

base/debug/trace_event.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // This header file defines the set of trace_event macros without specifying
 // how the events actually get collected and stored. If you need to expose trace
 // events to some other universe, you can copy-and-paste this file as well as
 // trace_event.h, modifying the macros contained there as necessary for the
 // target platform. The end result is that multiple libraries can funnel events
 // through to a shared trace event collector.
@@ skipping 493 matching lines @@
         value1_name, static_cast<int>(value1_val), \
         value2_name, static_cast<int>(value2_val))
 #define TRACE_COPY_COUNTER_ID2(category_group, name, id, value1_name, \
         value1_val, value2_name, value2_val) \
     INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_COUNTER, \
         category_group, name, id, TRACE_EVENT_FLAG_COPY, \
         value1_name, static_cast<int>(value1_val), \
         value2_name, static_cast<int>(value2_val))
 
 
 // Records a single ASYNC_BEGIN event called "name" immediately, with 0, 1 or 2

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

I want to discourage people from using this api. please update the docs so that
people are steered to the nestable version. This should only be used by legacy
code and the comments should effectively say this.

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

Done.

 // 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_BEGIN event with the ASYNC_END event. ASYNC
 //   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.
 //
 // An asynchronous operation can consist of multiple phases. The first phase is
 // defined by the ASYNC_BEGIN calls. Additional phases can be defined using the
 // ASYNC_STEP_INTO or ASYNC_STEP_PAST macros. The ASYNC_STEP_INTO macro will
 // annotate the block following the call. The ASYNC_STEP_PAST macro will
 // annotate the block prior to the call. Note that any particular event must use
 // 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
 // args.
 #define TRACE_EVENT_ASYNC_BEGIN0(category_group, name, id) \
     INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_BEGIN, \
         category_group, name, id, TRACE_EVENT_FLAG_NONE)
 #define TRACE_EVENT_ASYNC_BEGIN1(category_group, name, id, arg1_name, \
         arg1_val) \
     INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_BEGIN, \
@@ skipping 84 matching lines @@
         arg1_name, arg1_val, arg2_name, arg2_val)
 
 // Similar to TRACE_EVENT_ASYNC_ENDx but with a custom |at| timestamp provided.
 #define TRACE_EVENT_ASYNC_END_WITH_TIMESTAMP0(category_group, \
         name, id, timestamp) \
     INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
         TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, \
         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.
 // - category and name strings must have application lifetime (statics or
 //   literals). They may not include " chars.
 // - |id| is used to match the FLOW_BEGIN event with the FLOW_END event. FLOW
 //   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.
@@ skipping 309 matching lines @@
 
 // Phase indicates the nature of an event entry. E.g. part of a begin/end pair.
 #define TRACE_EVENT_PHASE_BEGIN    ('B')
 #define TRACE_EVENT_PHASE_END      ('E')
 #define TRACE_EVENT_PHASE_COMPLETE ('X')
 #define TRACE_EVENT_PHASE_INSTANT  ('I')
 #define TRACE_EVENT_PHASE_ASYNC_BEGIN ('S')
 #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')
 #define TRACE_EVENT_PHASE_METADATA ('M')
 #define TRACE_EVENT_PHASE_COUNTER  ('C')
 #define TRACE_EVENT_PHASE_SAMPLE  ('P')
 #define TRACE_EVENT_PHASE_CREATE_OBJECT ('N')
 #define TRACE_EVENT_PHASE_SNAPSHOT_OBJECT ('O')
 #define TRACE_EVENT_PHASE_DELETE_OBJECT ('D')
 
@@ skipping 550 matching lines @@
   const char* name_;
   IDType id_;
 
   DISALLOW_COPY_AND_ASSIGN(TraceScopedTrackableObject);
 };
 
 } // namespace debug
 } // namespace base
 
 #endif /* BASE_DEBUG_TRACE_EVENT_H_ */