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 616 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 NET_LOG_BEGIN event called "name" immediately, with 2
+// associated arguments. If the category is not enabled, then this

[nduca, 2014/09/03 05:37:23]

not just 2

[xunjieli, 2014/09/03 14:51:09]

There are two associated arguments right? arg1 and arg2. Or should I count name
and id too? The other examples in this file only count arg1 and arg2. 
On 2014/09/03 05:37:23, nduca wrote:

+// does nothing.
+// - category and name strings must have application lifetime (statics or
+//   literals). They may not include " chars.
+// - |id| is used to match the NET_LOG_BEGIN event with the NET_LOG_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.
+// NET_LOG_ events are supposed to be used for logging NetLog events only.

[nduca, 2014/09/03 05:37:24]

Please retitle to nestable_async_*.

Tracing is neutral to all libraries that use it. We seek abstractions that allow
us to represent the behavior of complex systems like the network stack, or the
graphics stack. But we never create abstractions that are purely for one domain
only.

So, please update the naming accordingly so that its not that this is for
netlog, but rather that what the abstraction we're creating here allows us to
represent. Your docs should explain when to use this, and when to use the
async_begin/end/step_into/after apis.

And you should update the *old* apis [the regular async apis] to clarify when to
use those.

Finally, please explain the nesting semantics. E.g. what happens if you say end,
before a begin. Or if you say begin, end end. Etc. This should be in the docs.

[xunjieli, 2014/09/03 14:51:09]

Done. Since dsinclair mentioned that the existing non-async counterparts does
nesting as well, how does tracing handle unmatched begin and end there? Should
parsing these nestable_async begin and end be the same as that one?

+
+#define TRACE_EVENT_NET_LOG_BEGIN2(category_group, name, id, arg1_name, \
+        arg1_val, arg2_name, arg2_val) \
+    INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NET_LOG_BEGIN, \
+        category_group, name, id, TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, \
+        arg2_name, arg2_val)
+// Records a single NET_LOG_END event for "name" immediately. If the category
+// is not enabled, then this does nothing.
+#define TRACE_EVENT_NET_LOG_END2(category_group, name, id, arg1_name, arg1_val, \
+        arg2_name, arg2_val) \
+    INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NET_LOG_END, \
+        category_group, name, id, TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, \
+        arg2_name, arg2_val)
+// Records a single NET_LOG_INSTANT event for "name" immediately.
+// If the category is not enabled, then this does nothing.
+#define TRACE_EVENT_NET_LOG_INSTANT2(category_group, name, id, arg1_name, \
+        arg1_val, arg2_name, arg2_val) \
+    INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NET_LOG_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_NET_LOG_BEGIN ('x')

[xunjieli, 2014/09/02 20:21:46]

Any letters that I can use? is x, y, z okay?

[nduca, 2014/09/03 05:37:24]

how about looking at the other ones and thinking a bit more carefully about it? 
i'd like to have a *reasoned* explanation of why the letters are chosen, not
just picking three letters.

you'll note async uses S/T/P, the flow uses s/t/f. Most of the letters are at
least somewhat related. Can you find something that makes sense?

[xunjieli, 2014/09/03 14:51:10]

Done. 
On 2014/09/03 05:37:24, nduca wrote:

+#define TRACE_EVENT_PHASE_NET_LOG_END ('y')
+#define TRACE_EVENT_PHASE_NET_LOG_INSTANT ('z')
 
 // 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_ */