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 512 matching lines @@
 //   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, NESTABLE_ASYNC_* 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 NESTABLE_ASYNC_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 NESTABLE_ASYNC_BEGIN event with the
+//   NESTABLE_ASYNC_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 NESTABLE_ASYNC_END event will be parsed as an instant event,
+//   and unmatched NESTABLE_ASYNC_BEGIN event will be parsed as an event, which
+//   starts at the time of the NESTABLE_ASYNC_BEGIN event and ends at the last
+//   NESTABLE_ASYNC_END event of that |id|.
+//
+//   NESTABLE_ASYNC_* APIs are used to capture asynchronous operations which can
+//   have multiple levels of nested events/phases. If an asynchronous operation
+//   only has one level of sub-events, one should consider using ASYNC_STEP_*.
+
+#define TRACE_EVENT_NESTABLE_ASYNC_BEGIN2(category_group, name, id, arg1_name, \
+        arg1_val, arg2_name, arg2_val) \
+    INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN, \
+        category_group, name, id, TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, \
+        arg2_name, arg2_val)
+// Records a single NESTABLE_ASYNC_END event for "name" immediately.
+// If the category is not enabled, then this does nothing.
+#define TRACE_EVENT_NESTABLE_ASYNC_END2(category_group, name, id, arg1_name, \
+        arg1_val, arg2_name, arg2_val) \
+    INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NESTABLE_ASYNC_END, \
+        category_group, name, id, TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, \
+        arg2_name, arg2_val)
+// Records a single NESTABLE_ASYNC_INSTANT event for "name" immediately.
+// If the category is not enabled, then this does nothing.
+#define TRACE_EVENT_NESTABLE_ASYNC_INSTANT2(category_group, name, id, \
+        arg1_name, arg1_val, arg2_name, arg2_val) \
+    INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NESTABLE_ASYNC_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 318 matching lines @@
 #define TRACE_EVENT_PHASE_ASYNC_END   ('F')
 #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')
+#define TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN ('b')
+#define TRACE_EVENT_PHASE_NESTABLE_ASYNC_END ('e')
+#define TRACE_EVENT_PHASE_NESTABLE_ASYNC_INSTANT ('n')

[dsinclair, 2014/09/03 15:02:47]

bikeshed: should these be ASYNC_NESTABLE (and the macros above) to keep them
consistent with the other ASYNC events? (And move them up with the other ASYNC_*
entries?

[xunjieli, 2014/09/03 15:09:15]

Done. ASYNC_NESTABLE does sound better. Thanks!

 
 // Flags for changing the behavior of TRACE_EVENT_API_ADD_TRACE_EVENT.
 #define TRACE_EVENT_FLAG_NONE         (static_cast<unsigned char>(0))
 #define TRACE_EVENT_FLAG_COPY         (static_cast<unsigned char>(1 << 0))
 #define TRACE_EVENT_FLAG_HAS_ID       (static_cast<unsigned char>(1 << 1))
 #define TRACE_EVENT_FLAG_MANGLE_ID    (static_cast<unsigned char>(1 << 2))
 #define TRACE_EVENT_FLAG_SCOPE_OFFSET (static_cast<unsigned char>(1 << 3))
 
 #define TRACE_EVENT_FLAG_SCOPE_MASK   (static_cast<unsigned char>( \
     TRACE_EVENT_FLAG_SCOPE_OFFSET | (TRACE_EVENT_FLAG_SCOPE_OFFSET << 1)))
@@ skipping 541 matching lines @@
   const char* name_;
   IDType id_;
 
   DISALLOW_COPY_AND_ASSIGN(TraceScopedTrackableObject);
 };
 
 } // namespace debug
 } // namespace base
 
 #endif /* BASE_DEBUG_TRACE_EVENT_H_ */