1// Copyright 2017 The Fuchsia Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style license that can be 3// found in the LICENSE file. 4 5// 6// The API for instrumenting C and C++ programs with trace events. 7// 8// This header defines macros which are used to record trace information during 9// program execution when tracing is enabled. Each trace event macro records 10// an event of a given type together with the current time, a category, name, 11// and named arguments containing additional information about the event. 12// 13// Where indicated, the category and name literal strings must point to 14// null-terminated static string constants whose memory address can be 15// cached by the string table for the lifetime of the trace session. 16// 17// Defining the NTRACE macro completely disables recording of trace events 18// in the compilation unit. 19// 20// For more control over how trace events are written, see <trace-engine/context.h>. 21// 22 23#pragma once 24 25#include <trace/event_internal.h> 26 27// Argument type macros used when writing trace events in C. 28// 29// When writing trace events in C, each trace argument value must be 30// individually wrapped with one of these macros to provide type information 31// for the argument. 32// 33// When writing trace events in C++, it is not necessary to wrap each trace 34// argument value with these macros since the compiler can infer the necessary 35// type information, with the exception of |TA_CHAR_ARRAY|, |TA_STRING_LITERAL|, 36// and |TA_KOID|. 37// 38// Use |TA_NULL| for null values. 39// Use |TA_INT32| for signed 32-bit integer values. 40// Use |TA_UINT32| for unsigned 32-bit integer values. 41// Use |TA_INT64| for signed 64-bit integer values. 42// Use |TA_UINT64| for unsigned 64-bit integer values. 43// Use |TA_DOUBLE| for double-precision floating point values. 44// Use |TA_CHAR_ARRAY| for character arrays with a length (copied rather than cached), required in C++. 45// Use |TA_STRING| for null-terminated dynamic strings (copied rather than cached). 46// Use |TA_STRING_LITERAL| for null-terminated static string constants (cached), required in C++. 47// Use |TA_POINTER| for pointer values (records the memory address, not the target). 48// Use |TA_KOID| for kernel object ids, required in C++. 49// 50// C or C++ Usage: (argument type macros required in C) 51// 52// char* chars = ...; 53// size_t length = ...; 54// const char* c_string = ...; 55// void* ptr = ...; 56// zx_koid_t koid = ...; 57// 58// TRACE_DURATION("category", "name", "arg", TA_NULL()); 59// TRACE_DURATION("category", "name", "arg", TA_INT32(-10)); 60// TRACE_DURATION("category", "name", "arg", TA_UINT32(10)); 61// TRACE_DURATION("category", "name", "arg", TA_INT64(-10)); 62// TRACE_DURATION("category", "name", "arg", TA_UINT64(10)); 63// TRACE_DURATION("category", "name", "arg", TA_DOUBLE(3.14)); 64// TRACE_DURATION("category", "name", "arg", TA_CHAR_ARRAY(chars, length)); 65// TRACE_DURATION("category", "name", "arg", TA_STRING(c_string)); 66// TRACE_DURATION("category", "name", "arg", TA_STRING_LITERAL("Hi!")); 67// TRACE_DURATION("category", "name", "arg", TA_POINTER(ptr)); 68// TRACE_DURATION("category", "name", "arg", TA_KOID(koid)); 69// 70// C++ Usage: (argument type macros only needed for certain types) 71// 72// char* chars = ...; 73// size_t length = ...; 74// const char* c_string = ...; 75// fbl::String fbl_string = ...; 76// std::string std_string = ...; 77// void* ptr = ...; 78// zx_koid_t koid = ...; 79// 80// TRACE_DURATION("category", "name", "arg", nullptr); 81// TRACE_DURATION("category", "name", "arg", -10); 82// TRACE_DURATION("category", "name", "arg", 10u); 83// TRACE_DURATION("category", "name", "arg", -10l); 84// TRACE_DURATION("category", "name", "arg", 10ul); 85// TRACE_DURATION("category", "name", "arg", 3.14); 86// TRACE_DURATION("category", "name", "arg", TA_CHAR_ARRAY(chars, length)); 87// TRACE_DURATION("category", "name", "arg", c_string); 88// TRACE_DURATION("category", "name", "arg", fbl_string); 89// TRACE_DURATION("category", "name", "arg", std_string); 90// TRACE_DURATION("category", "name", "arg", TA_STRING_LITERAL("Hi!")); 91// TRACE_DURATION("category", "name", "arg", ptr); 92// TRACE_DURATION("category", "name", "arg", TA_KOID(koid)); 93// 94#define TA_NULL() (trace_make_null_arg_value()) 95#define TA_INT32(int32_value) (trace_make_int32_arg_value(int32_value)) 96#define TA_UINT32(uint32_value) (trace_make_uint32_arg_value(uint32_value)) 97#define TA_INT64(int64_value) (trace_make_int64_arg_value(int64_value)) 98#define TA_UINT64(uint64_value) (trace_make_uint64_arg_value(uint64_value)) 99#define TA_DOUBLE(double_value) (trace_make_double_arg_value(double_value)) 100#define TA_CHAR_ARRAY(string_value, length) \ 101 (trace_make_string_arg_value( \ 102 trace_make_inline_string_ref((string_value), (length)))) 103#define TA_STRING(string_value) \ 104 (trace_make_string_arg_value( \ 105 trace_make_inline_c_string_ref(string_value))) 106#define TA_STRING_LITERAL(string_literal_value) \ 107 (trace_make_string_arg_value( \ 108 TRACE_INTERNAL_MAKE_LITERAL_STRING_REF(string_literal_value))) 109#define TA_POINTER(pointer_value) (trace_make_pointer_arg_value((uintptr_t)pointer_value)) 110#define TA_KOID(koid_value) (trace_make_koid_arg_value(koid_value)) 111 112// Returns true if tracing is enabled. 113// 114// Usage: 115// 116// if (TRACE_ENABLED()) { 117// // do something possibly expensive only when tracing is enabled 118// } 119// 120#ifndef NTRACE 121#define TRACE_ENABLED() (trace_is_enabled()) 122#else 123#define TRACE_ENABLED() (false) 124#endif // NTRACE 125 126// Returns true if tracing of the specified category has been enabled (which 127// implies that |TRACE_ENABLED()| is also true). 128// 129// |category_literal| must be a null-terminated static string constant. 130// 131// Usage: 132// 133// if (TRACE_CATEGORY_ENABLED("category")) { 134// // do something possibly expensive only when tracing this category 135// } 136// 137#ifndef NTRACE 138#define TRACE_CATEGORY_ENABLED(category_literal) \ 139 (trace_is_category_enabled(category_literal)) 140#else 141#define TRACE_CATEGORY_ENABLED(category_literal) ((void)(category_literal), false) 142#endif // NTRACE 143 144// Returns a new unique 64-bit unsigned integer (within this process). 145// Each invocation returns a different non-zero value. 146// Useful for generating identifiers for async and flow events. 147// 148// Usage: 149// 150// trace_async_id_t async_id = TRACE_NONCE(); 151// TRACE_ASYNC_BEGIN("category", "name", async_id); 152// // a little while later... 153// TRACE_ASYNC_END("category", "name", async_id); 154// 155#define TRACE_NONCE() (trace_generate_nonce()) 156 157// Writes an instant event representing a single moment in time (a probe). 158// 159// 0 to 15 arguments can be associated with the event, each of which is used 160// to annotate the moment with additional information. 161// 162// |category_literal| and |name_literal| must be null-terminated static string constants. 163// |scope| is |TRACE_SCOPE_THREAD|, |TRACE_SCOPE_PROCESS|, or |TRACE_SCOPE_GLOBAL|. 164// |args| is the list of argument key/value pairs. 165// 166// Usage: 167// 168// TRACE_INSTANT("category", "name", TRACE_SCOPE_PROCESS, "x", TA_INT32(42)); 169// 170#define TRACE_INSTANT(category_literal, name_literal, scope, args...) \ 171 TRACE_INTERNAL_INSTANT((category_literal), (name_literal), (scope), args) 172 173// Writes a counter event with the specified id. 174// 175// The arguments to this event are numeric samples are typically represented by 176// the visualizer as a stacked area chart. The id serves to distinguish multiple 177// instances of counters which share the same category and name within the 178// same process. 179// 180// 1 to 15 numeric arguments can be associated with the event, each of which is 181// interpreted as a distinct time series. 182// 183// |category_literal| and |name_literal| must be null-terminated static string constants. 184// |counter_id| is the correlation id of the counter. 185// Must be unique for a given process, category, and name combination. 186// |args| is the list of argument key/value pairs. 187// 188// Usage: 189// 190// trace_counter_id_t counter_id = 555; 191// TRACE_COUNTER("category", "name", counter_id, "x", TA_INT32(42), "y", TA_DOUBLE(2.0)) 192// 193#define TRACE_COUNTER(category_literal, name_literal, counter_id, arg1, args...) \ 194 TRACE_INTERNAL_COUNTER((category_literal), (name_literal), (counter_id), arg1, ##args) 195 196// Writes a duration event which ends when the current scope exits. 197// 198// Durations describe work which is happening synchronously on one thread. 199// They can be nested to represent a control flow stack. 200// 201// 0 to 15 arguments can be associated with the event, each of which is used 202// to annotate the duration with additional information. 203// 204// |category_literal| and |name_literal| must be null-terminated static string constants. 205// |args| is the list of argument key/value pairs. 206// 207// Usage: 208// 209// void function(int arg) { 210// TRACE_DURATION("category", "name", "arg", TA_INT32(arg)); 211// // do something useful here 212// } 213// 214#define TRACE_DURATION(category_literal, name_literal, args...) \ 215 TRACE_INTERNAL_DURATION((category_literal), (name_literal), args) 216 217// Writes a duration begin event only. 218// This event must be matched by a duration end event with the same category and name. 219// 220// Durations describe work which is happening synchronously on one thread. 221// They can be nested to represent a control flow stack. 222// 223// 0 to 15 arguments can be associated with the event, each of which is used 224// to annotate the duration with additional information. The arguments provided 225// to matching duration begin and duration end events are combined together in 226// the trace; it is not necessary to repeat them. 227// 228// |category_literal| and |name_literal| must be null-terminated static string constants. 229// |args| is the list of argument key/value pairs. 230// 231// Usage: 232// 233// TRACE_DURATION_BEGIN("category", "name", "x", TA_INT32(42)); 234// 235#define TRACE_DURATION_BEGIN(category_literal, name_literal, args...) \ 236 TRACE_INTERNAL_DURATION_BEGIN((category_literal), (name_literal), args) 237 238// Writes a duration end event only. 239// 240// Durations describe work which is happening synchronously on one thread. 241// They can be nested to represent a control flow stack. 242// 243// 0 to 15 arguments can be associated with the event, each of which is used 244// to annotate the duration with additional information. The arguments provided 245// to matching duration begin and duration end events are combined together in 246// the trace; it is not necessary to repeat them. 247// 248// |category_literal| and |name_literal| must be null-terminated static string constants. 249// |args| is the list of argument key/value pairs. 250// 251// Usage: 252// 253// TRACE_DURATION_END("category", "name", "x", TA_INT32(42)); 254// 255#define TRACE_DURATION_END(category_literal, name_literal, args...) \ 256 TRACE_INTERNAL_DURATION_END((category_literal), (name_literal), args) 257 258// Writes an asynchronous begin event with the specified id. 259// This event may be followed by async instant events and must be matched by 260// an async end event with the same category, name, and id. 261// 262// Asynchronous events describe work which is happening asynchronously and which 263// may span multiple threads. Asynchronous events do not nest. The id serves 264// to correlate the progress of distinct asynchronous operations which share 265// the same category and name within the same process. 266// 267// 0 to 15 arguments can be associated with the event, each of which is used 268// to annotate the asynchronous operation with additional information. The 269// arguments provided to matching async begin, async instant, and async end 270// events are combined together in the trace; it is not necessary to repeat them. 271// 272// |category_literal| and |name_literal| must be null-terminated static string constants. 273// |async_id| is the correlation id of the asynchronous operation. 274// Must be unique for a given process, category, and name combination. 275// |args| is the list of argument key/value pairs. 276// 277// Usage: 278// 279// trace_async_id_t async_id = 555; 280// TRACE_ASYNC_BEGIN("category", "name", async_id, "x", TA_INT32(42)); 281// 282#define TRACE_ASYNC_BEGIN(category_literal, name_literal, async_id, args...) \ 283 TRACE_INTERNAL_ASYNC_BEGIN((category_literal), (name_literal), (async_id), args) 284 285// Writes an asynchronous instant event with the specified id. 286// 287// Asynchronous events describe work which is happening asynchronously and which 288// may span multiple threads. Asynchronous events do not nest. The id serves 289// to correlate the progress of distinct asynchronous operations which share 290// the same category and name within the same process. 291// 292// 0 to 15 arguments can be associated with the event, each of which is used 293// to annotate the asynchronous operation with additional information. The 294// arguments provided to matching async begin, async instant, and async end 295// events are combined together in the trace; it is not necessary to repeat them. 296// 297// |category_literal| and |name_literal| must be null-terminated static string constants. 298// |async_id| is the correlation id of the asynchronous operation. 299// Must be unique for a given process, category, and name combination. 300// |args| is the list of argument key/value pairs. 301// 302// Usage: 303// 304// trace_async_id_t async_id = 555; 305// TRACE_ASYNC_INSTANT("category", "name", async_id, "x", TA_INT32(42)); 306// 307#define TRACE_ASYNC_INSTANT(category_literal, name_literal, async_id, args...) \ 308 TRACE_INTERNAL_ASYNC_INSTANT((category_literal), (name_literal), (async_id), args) 309 310// Writes an asynchronous end event with the specified id. 311// 312// Asynchronous events describe work which is happening asynchronously and which 313// may span multiple threads. Asynchronous events do not nest. The id serves 314// to correlate the progress of distinct asynchronous operations which share 315// the same category and name within the same process. 316// 317// 0 to 15 arguments can be associated with the event, each of which is used 318// to annotate the asynchronous operation with additional information. The 319// arguments provided to matching async begin, async instant, and async end 320// events are combined together in the trace; it is not necessary to repeat them. 321// 322// |category_literal| and |name_literal| must be null-terminated static string constants. 323// |async_id| is the correlation id of the asynchronous operation. 324// Must be unique for a given process, category, and name combination. 325// |args| is the list of argument key/value pairs. 326// 327// Usage: 328// 329// trace_async_id_t async_id = 555; 330// TRACE_ASYNC_END("category", "name", async_id, "x", TA_INT32(42)); 331// 332#define TRACE_ASYNC_END(category_literal, name_literal, async_id, args...) \ 333 TRACE_INTERNAL_ASYNC_END((category_literal), (name_literal), (async_id), args) 334 335// Writes a flow begin event with the specified id. 336// This event may be followed by flow steps events and must be matched by 337// a flow end event with the same category, name, and id. 338// 339// Flow events describe control flow handoffs between threads or across processes. 340// They are typically represented as arrows in a visualizer. Flow arrows are 341// from the end of the duration event which encloses the beginning of the flow 342// to the beginning of the duration event which encloses the next step or the 343// end of the flow. The id serves to correlate flows which share the same 344// category and name across processes. 345// 346// This event must be enclosed in a duration event which represents where 347// the flow handoff occurs. 348// 349// 0 to 15 arguments can be associated with the event, each of which is used 350// to annotate the flow with additional information. The arguments provided 351// to matching flow begin, flow step, and flow end events are combined together 352// in the trace; it is not necessary to repeat them. 353// 354// |category_literal| and |name_literal| must be null-terminated static string constants. 355// |flow_id| is the correlation id of the flow. 356// Must be unique for a given category and name combination. 357// |args| is the list of argument key/value pairs. 358// 359// Usage: 360// 361// trace_flow_id_t flow_id = 555; 362// TRACE_FLOW_BEGIN("category", "name", flow_id, "x", TA_INT32(42)); 363// 364#define TRACE_FLOW_BEGIN(category_literal, name_literal, flow_id, args...) \ 365 TRACE_INTERNAL_FLOW_BEGIN((category_literal), (name_literal), (flow_id), args) 366 367// Writes a flow step event with the specified id. 368// 369// Flow events describe control flow handoffs between threads or across processes. 370// They are typically represented as arrows in a visualizer. Flow arrows are 371// from the end of the duration event which encloses the beginning of the flow 372// to the beginning of the duration event which encloses the next step or the 373// end of the flow. The id serves to correlate flows which share the same 374// category and name across processes. 375// 376// This event must be enclosed in a duration event which represents where 377// the flow handoff occurs. 378// 379// 0 to 15 arguments can be associated with the event, each of which is used 380// to annotate the flow with additional information. The arguments provided 381// to matching flow begin, flow step, and flow end events are combined together 382// in the trace; it is not necessary to repeat them. 383// 384// |category_literal| and |name_literal| must be null-terminated static string constants. 385// |flow_id| is the correlation id of the flow. 386// Must be unique for a given category and name combination. 387// |args| is the list of argument key/value pairs. 388// 389// Usage: 390// 391// trace_flow_id_t flow_id = 555; 392// TRACE_FLOW_STEP("category", "name", flow_id, "x", TA_INT32(42)); 393// 394#define TRACE_FLOW_STEP(category_literal, name_literal, flow_id, args...) \ 395 TRACE_INTERNAL_FLOW_STEP((category_literal), (name_literal), (flow_id), args) 396 397// Writes a flow end event with the specified id. 398// 399// Flow events describe control flow handoffs between threads or across processes. 400// They are typically represented as arrows in a visualizer. Flow arrows are 401// from the end of the duration event which encloses the beginning of the flow 402// to the beginning of the duration event which encloses the next step or the 403// end of the flow. The id serves to correlate flows which share the same 404// category and name across processes. 405// 406// This event must be enclosed in a duration event which represents where 407// the flow handoff occurs. 408// 409// 0 to 15 arguments can be associated with the event, each of which is used 410// to annotate the flow with additional information. The arguments provided 411// to matching flow begin, flow step, and flow end events are combined together 412// in the trace; it is not necessary to repeat them. 413// 414// |category_literal| and |name_literal| must be null-terminated static string constants. 415// |flow_id| is the correlation id of the flow. 416// Must be unique for a given category and name combination. 417// |args| is the list of argument key/value pairs. 418// 419// Usage: 420// 421// trace_flow_id_t id = 555; 422// TRACE_FLOW_END("category", "name", flow_id, "x", TA_INT32(42)); 423// 424#define TRACE_FLOW_END(category_literal, name_literal, flow_id, args...) \ 425 TRACE_INTERNAL_FLOW_END((category_literal), (name_literal), (flow_id), args) 426 427// Writes a description of a kernel object indicated by |handle|, 428// including its koid, name, and the supplied arguments. 429// 430// 0 to 15 arguments can be associated with the record, each of which is used 431// to annotate the handle with additional information. 432// 433// |handle| is the handle of the object being described. 434// |args| is the list of argument key/value pairs. 435// 436// Usage: 437// 438// zx_handle_t handle = ...; 439// TRACE_KERNEL_OBJECT(handle, "description", TA_STRING("some object")); 440// 441#define TRACE_KERNEL_OBJECT(handle, args...) \ 442 TRACE_INTERNAL_KERNEL_OBJECT((handle), args) 443 444// Writes a blob of binary data to the trace buffer. 445// 446// |type| is the type of the blob, and must be one of the enums in type 447// |trace_blob_type_t|. 448// |name_ref| is the name of the blob, and must be a string literal. 449// |blob| is a pointer to the data. 450// |blob_size| is the size, in bytes, of the data. 451// 452// A size of zero is ok. The maximum size of a blob is defined by 453// TRACE_MAX_BLOB_SIZE which is slighly less than 32K. 454// Exercise caution when emitting blob records: space is shared with all 455// trace records and large blobs can eat up space fast. 456// The blob must fit in the remaining space in the buffer. If the blob does 457// not fit the call silently fails, as do all calls that write trace records 458// when the buffer is full. 459// 460// Usage: 461// size_t blob_size = ...; 462// const void* blob = ...; 463// TRACE_BLOB(TRACE_BLOB_TYPE_DATA, "my-blob", blob, blob_size); 464// 465#define TRACE_BLOB(type, name, blob, blob_size) \ 466 TRACE_INTERNAL_BLOB((type), (name), (blob), (blob_size)) 467 468// Writes a virtual thread duration begin event. 469// This event must be matched by a duration end event with the same category, 470// name and virtual thread. 471// 472// Virtual thread durations describe work which is happening synchronously on 473// a timeline other than the CPU's (E.g. the GPU). 474// They can be nested to represent a control flow stack. 475// The virtual thread id serves to identify the timeline within the process. 476// 477// 0 to 15 arguments can be associated with the event, each of which is used 478// to annotate the duration with additional information. The arguments provided 479// to matching duration begin and duration end events are combined together in 480// the trace; it is not necessary to repeat them. 481// 482// |category_literal|, |name_literal| and |vthread_literal| must be 483// null-terminated static string constants. 484// |vthread_id| is the correlation id of the virtual thread. 485// Must be unique for a given process. 486// |args| is the list of argument key/value pairs. 487// 488// Usage: 489// 490// trace_vthread_id_t vthread_id = 444; 491// TRACE_VTHREAD_DURATION_BEGIN("category", "name", "vthread", vthread_id, 492// "x", TA_INT32(42)); 493// 494#define TRACE_VTHREAD_DURATION_BEGIN(category_literal, name_literal, \ 495 vthread_literal, vthread_id, args...) \ 496 TRACE_INTERNAL_VTHREAD_DURATION_BEGIN((category_literal), (name_literal), \ 497 (vthread_literal), (vthread_id), args) 498 499// Writes a virtual thread duration end event. 500// 501// Virtual thread durations describe work which is happening synchronously on 502// a timeline other than the CPU's (E.g. the GPU). 503// They can be nested to represent a control flow stack. 504// The virtual thread id serves to identify the timeline within the process. 505// 506// 0 to 15 arguments can be associated with the event, each of which is used 507// to annotate the duration with additional information. The arguments provided 508// to matching duration begin and duration end events are combined together in 509// the trace; it is not necessary to repeat them. 510// 511// |category_literal|, |name_literal| and |vthread_literal| must be 512// null-terminated static string constants. 513// |vthread_id| is the correlation id of the virtual thread. 514// Must be unique for a given process. 515// |args| is the list of argument key/value pairs. 516// 517// Usage: 518// 519// trace_vthread_id_t vthread_id = 444; 520// TRACE_VTHREAD_DURATION_END("category", "name", "vthread", vthread_id, 521// "x", TA_INT32(42)); 522// 523#define TRACE_VTHREAD_DURATION_END(category_literal, name_literal, \ 524 vthread_literal, vthread_id, args...) \ 525 TRACE_INTERNAL_VTHREAD_DURATION_END((category_literal), (name_literal), \ 526 (vthread_literal), (vthread_id), args) 527 528// Writes a virtual thread flow begin event with the specified id. 529// This event may be followed by flow steps events and must be matched by 530// a flow end event with the same category, name, virtual thread and id. 531// 532// Flow events describe control flow handoffs between threads or across processes. 533// They are typically represented as arrows in a visualizer. Flow arrows are 534// from the end of the duration event which encloses the beginning of the flow 535// to the beginning of the duration event which encloses the next step or the 536// end of the flow. The id serves to correlate flows which share the same 537// category and name across processes. 538// 539// This event must be enclosed in a duration event which represents where 540// the flow handoff occurs. 541// 542// 0 to 15 arguments can be associated with the event, each of which is used 543// to annotate the flow with additional information. The arguments provided 544// to matching flow begin, flow step, and flow end events are combined together 545// in the trace; it is not necessary to repeat them. 546// 547// |category_literal|, |name_literal| and |vthread_literal| must be 548// null-terminated static string constants. 549// |vthread_id| is the correlation id of the virtual thread. 550// Must be unique for a given process. 551// |flow_id| is the correlation id of the flow. 552// Must be unique for a given category and name combination. 553// |args| is the list of argument key/value pairs. 554// 555// Usage: 556// 557// trace_vthread_id_t vthread_id = 444; 558// trace_flow_id_t flow_id = 555; 559// TRACE_VTHREAD_FLOW_BEGIN("category", "name", "vthread", vthread_id, 560// flow_id, "x", TA_INT32(42)); 561// 562#define TRACE_VTHREAD_FLOW_BEGIN(category_literal, name_literal, \ 563 vthread_literal, vthread_id, flow_id, \ 564 args...) \ 565 TRACE_INTERNAL_VTHREAD_FLOW_BEGIN((category_literal), (name_literal), \ 566 (vthread_literal), (vthread_id), \ 567 (flow_id), args) 568 569// Writes a virtual thread flow step event with the specified id. 570// 571// Flow events describe control flow handoffs between threads or across processes. 572// They are typically represented as arrows in a visualizer. Flow arrows are 573// from the end of the duration event which encloses the beginning of the flow 574// to the beginning of the duration event which encloses the next step or the 575// end of the flow. The id serves to correlate flows which share the same 576// category and name across processes. 577// 578// This event must be enclosed in a duration event which represents where 579// the flow handoff occurs. 580// 581// 0 to 15 arguments can be associated with the event, each of which is used 582// to annotate the flow with additional information. The arguments provided 583// to matching flow begin, flow step, and flow end events are combined together 584// in the trace; it is not necessary to repeat them. 585// 586// |category_literal|, |name_literal| and |vthread_literal| must be 587// null-terminated static string constants. 588// |vthread_id| is the correlation id of the virtual thread. 589// Must be unique for a given process. 590// |flow_id| is the correlation id of the flow. 591// Must be unique for a given category and name combination. 592// |args| is the list of argument key/value pairs. 593// 594// Usage: 595// 596// trace_vthread_id_t vthread_id = 444; 597// trace_flow_id_t flow_id = 555; 598// TRACE_VTHREAD_FLOW_STEP("category", "name", "vthread", vthread_id, 599// flow_id, "x", TA_INT32(42)); 600// 601#define TRACE_VTHREAD_FLOW_STEP(category_literal, name_literal, \ 602 vthread_literal, vthread_id, flow_id, \ 603 args...) \ 604 TRACE_INTERNAL_VTHREAD_FLOW_STEP((category_literal), (name_literal), \ 605 (vthread_literal), (vthread_id), \ 606 (flow_id), args) 607 608// Writes a virtual thread flow end event with the specified id. 609// 610// Flow events describe control flow handoffs between threads or across processes. 611// They are typically represented as arrows in a visualizer. Flow arrows are 612// from the end of the duration event which encloses the beginning of the flow 613// to the beginning of the duration event which encloses the next step or the 614// end of the flow. The id serves to correlate flows which share the same 615// category and name across processes. 616// 617// This event must be enclosed in a duration event which represents where 618// the flow handoff occurs. 619// 620// 0 to 15 arguments can be associated with the event, each of which is used 621// to annotate the flow with additional information. The arguments provided 622// to matching flow begin, flow step, and flow end events are combined together 623// in the trace; it is not necessary to repeat them. 624// 625// |category_literal|, |name_literal| and |vthread_literal| must be 626// null-terminated static string constants. 627// |vthread_id| is the correlation id of the virtual thread. 628// Must be unique for a given process. 629// |flow_id| is the correlation id of the flow. 630// Must be unique for a given category and name combination. 631// |args| is the list of argument key/value pairs. 632// 633// Usage: 634// 635// trace_vthread_id_t vthread_id = 444; 636// trace_flow_id_t flow_id = 555; 637// TRACE_VTHREAD_FLOW_END("category", "name", "vthread", vthread_id, 638// flow_id, "x", TA_INT32(42)); 639// 640#define TRACE_VTHREAD_FLOW_END(category_literal, name_literal, \ 641 vthread_literal, vthread_id, flow_id, \ 642 args...) \ 643 TRACE_INTERNAL_VTHREAD_FLOW_END((category_literal), (name_literal), \ 644 (vthread_literal), (vthread_id), \ 645 (flow_id), args) 646