Phosphor
Macros
phosphor.h File Reference
#include "phosphor-internal.h"
#include "trace_log.h"

Go to the source code of this file.

Macros

#define PHOSPHOR_INSTANCE   phosphor::TraceLog::getInstance()
 
#define PHOSPHOR_PTR(arg)   arg
 
#define PHOSPHOR_INLINE_STR(arg)   phosphor::inline_zstring<8>(arg)
 
#define PHOSPHOR_INLINE_STR_N(arg, len)   phosphor::inline_zstring<8>(arg, len)
 
#define PHOSPHOR_DISABLED   0
 
#define PHOSPHOR_ENABLED   !PHOSPHOR_DISABLED
 
#define TRACE_EVENT_START(category, name, ...)
 
#define TRACE_EVENT_START0(category, name)
 
#define TRACE_EVENT_END(category, name, ...)
 
#define TRACE_EVENT_END0(category, name)
 
#define TRACE_EVENT_START1(category, name, arg1_name, arg1)
 
#define TRACE_EVENT_END1(category, name, arg1_name, arg1)
 
#define TRACE_EVENT_START2(category, name, arg1_name, arg1, arg2_name, arg2)
 
#define TRACE_EVENT_END2(category, name, arg1_name, arg1, arg2_name, arg2)
 
#define TRACE_EVENT(category, name, ...)
 
#define TRACE_EVENT0(category, name)
 
#define TRACE_EVENT1(category, name, arg1_name, arg1)
 
#define TRACE_EVENT2(category, name, arg1_name, arg1, arg2_name, arg2)
 
#define TRACE_FUNCTION(category, ...)   TRACE_EVENT(category, __func__, __VA_ARGS__)
 
#define TRACE_FUNCTION0(category)   TRACE_EVENT0(category, __func__)
 
#define TRACE_FUNCTION1(category, arg1_name, arg1)   TRACE_EVENT1(category, __func__, arg1_name, arg1)
 
#define TRACE_FUNCTION2(category, arg1_name, arg1, arg2_name, arg2)   TRACE_EVENT2(category, __func__, arg1_name, arg1, arg2_name, arg2)
 
#define TRACE_LOCKGUARD(mutex, category, name)
 
#define TRACE_ASYNC_START(category, name, id, ...)
 
#define TRACE_ASYNC_START0(category, name, id)
 
#define TRACE_ASYNC_START1(category, name, id, arg1_name, arg1)
 
#define TRACE_ASYNC_END(category, name, id, ...)
 
#define TRACE_ASYNC_END0(category, name, id)
 
#define TRACE_ASYNC_END1(category, name, id, arg1_name, arg1)
 
#define TRACE_INSTANT(category, name, ...)
 
#define TRACE_INSTANT0(category, name)
 
#define TRACE_INSTANT1(category, name, arg1_name, arg1)
 
#define TRACE_INSTANT2(category, name, arg1_name, arg1, arg2_name, arg2)
 
#define TRACE_GLOBAL(category, name, ...)
 
#define TRACE_GLOBAL0(category, name)
 
#define TRACE_GLOBAL1(category, name, arg1_name, arg1)
 
#define TRACE_GLOBAL2(category, name, arg1_name, arg1, arg2_name, arg2)
 

Detailed Description

Phosphor Event Tracing

Phosphor is an event tracing framework and can be used for tracing high frequency events. This file describes the instrumentation API used for adding tracing to a user application.

The management / configuration API is formed by the TraceLog and TraceConfig classes listed in trace_log.h

The instrumentation API is formed by four groups of events:

  • Synchronous
  • Asynchronous
  • Instant
  • Global

In addition each group will have events macros in one of three styles, either with 0 arguments, with multiple arguments or with multiple arguments and with argument names. Macros suffixed with 0, such as TRACE_EVENT_START0, can be used with 0 arguments.

Macros without the 0 suffix can be given 1 or 2 arguments - they might work with 0 arguments but some compilers will generate warnings due to 0-argument variadic macros.

Macros with either a '1' or '2' suffix can be given 1 or 2 arguments respectively, they also take an argument name (as a string literal) before each of their respective arguments. Example: 

TRACE_EVENT2("category", "name", "arg_name1", 1, "arg_name2", 2);

Only a limited set of data-types can be used as arguments, generally this includes most primitive data-types that are 8-bytes or less in size. In addition, string-literals or long living cstrings can be used so long as the pointer remains valid while tracing is enabled. A non-exhaustive list of these data-types include:

  • boolean
  • int
  • unsigned int
  • float
  • double
  • char* pointing to a cstring
  • void*

Macro Definition Documentation

#define PHOSPHOR_INLINE_STR (   arg)    phosphor::inline_zstring<8>(arg)

Utility for inlining up to 8 bytes of any string, including dynamically allocated strings. Accepts std::string or char* as argument. Strings longer than 8 bytes will be truncated.

#define PHOSPHOR_INSTANCE   phosphor::TraceLog::getInstance()

Defined to return the global singleton instance of the Phosphor TraceLog

#define PHOSPHOR_PTR (   arg)    arg

Deprecated alias for converting pointers to a const void*. Unnecessary as Phosphor now supports arbitrary pointer types for TraceArguments.