libraries/source/spidermonkey/include-win32-release/mozilla/BaseProfilerLabels.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 // This header contains all definitions related to Base Profiler labels (outside
   8 // of XUL).
   9 // It is safe to include unconditionally, and only defines empty macros if
  10 // MOZ_GECKO_PROFILER is not set.
  11
  12 #ifndef BaseProfilerLabels_h
  13 #define BaseProfilerLabels_h
  14
  15 #ifndef MOZ_GECKO_PROFILER
  16
  17 #  define AUTO_BASE_PROFILER_LABEL(label, categoryPair)
  18 #  define AUTO_BASE_PROFILER_LABEL_CATEGORY_PAIR(categoryPair)
  19 #  define AUTO_BASE_PROFILER_LABEL_DYNAMIC_CSTR(label, categoryPair, cStr)
  20 #  define AUTO_BASE_PROFILER_LABEL_DYNAMIC_STRING(label, categoryPair, str)
  21 #  define AUTO_BASE_PROFILER_LABEL_FAST(label, categoryPair, ctx)
  22 #  define AUTO_BASE_PROFILER_LABEL_DYNAMIC_FAST(label, dynamicString, \
  23                                                 categoryPair, ctx, flags)
  24
  25 #else  // !MOZ_GECKO_PROFILER
  26
  27 #  include "BaseProfilingStack.h"
  28
  29 #  include "mozilla/Attributes.h"
  30 #  include "mozilla/Maybe.h"
  31 #  include "mozilla/BaseProfilerState.h"
  32 #  include "mozilla/ThreadLocal.h"
  33
  34 #  include <stdint.h>
  35 #  include <string>
  36
  37 // Macros used by the AUTO_PROFILER_* macros.
  38 #  define BASE_PROFILER_RAII_PASTE(id, line) id##line
  39 #  define BASE_PROFILER_RAII_EXPAND(id, line) BASE_PROFILER_RAII_PASTE(id, line)
  40 #  define BASE_PROFILER_RAII BASE_PROFILER_RAII_EXPAND(raiiObject, __LINE__)
  41
  42 namespace mozilla::baseprofiler {
  43
  44 // Insert an RAII object in this scope to enter a label stack frame. Any
  45 // samples collected in this scope will contain this label in their stack.
  46 // The label argument must be a static C string. It is usually of the
  47 // form "ClassName::FunctionName". (Ideally we'd use the compiler to provide
  48 // that for us, but __func__ gives us the function name without the class
  49 // name.) If the label applies to only part of a function, you can qualify it
  50 // like this: "ClassName::FunctionName:PartName".
  51 //
  52 // Use AUTO_BASE_PROFILER_LABEL_DYNAMIC_* if you want to add additional /
  53 // dynamic information to the label stack frame.
  54 #  define AUTO_BASE_PROFILER_LABEL(label, categoryPair)            \
  55     ::mozilla::baseprofiler::AutoProfilerLabel BASE_PROFILER_RAII( \
  56         label, nullptr,                                            \
  57         ::mozilla::baseprofiler::ProfilingCategoryPair::categoryPair)
  58
  59 // Similar to AUTO_BASE_PROFILER_LABEL, but with only one argument: the category
  60 // pair. The label string is taken from the category pair. This is convenient
  61 // for labels like
  62 // AUTO_BASE_PROFILER_LABEL_CATEGORY_PAIR(GRAPHICS_LayerBuilding) which would
  63 // otherwise just repeat the string.
  64 #  define AUTO_BASE_PROFILER_LABEL_CATEGORY_PAIR(categoryPair)         \
  65     ::mozilla::baseprofiler::AutoProfilerLabel BASE_PROFILER_RAII(     \
  66         "", nullptr,                                                   \
  67         ::mozilla::baseprofiler::ProfilingCategoryPair::categoryPair,  \
  68         uint32_t(::mozilla::baseprofiler::ProfilingStackFrame::Flags:: \
  69                      LABEL_DETERMINED_BY_CATEGORY_PAIR))
  70
  71 // Similar to AUTO_BASE_PROFILER_LABEL, but with an additional string. The
  72 // inserted RAII object stores the cStr pointer in a field; it does not copy the
  73 // string.
  74 //
  75 // WARNING: This means that the string you pass to this macro needs to live at
  76 // least until the end of the current scope. Be careful using this macro with
  77 // ns[C]String; the other AUTO_BASE_PROFILER_LABEL_DYNAMIC_* macros below are
  78 // preferred because they avoid this problem.
  79 //
  80 // If the profiler samples the current thread and walks the label stack while
  81 // this RAII object is on the stack, it will copy the supplied string into the
  82 // profile buffer. So there's one string copy operation, and it happens at
  83 // sample time.
  84 //
  85 // Compare this to the plain AUTO_BASE_PROFILER_LABEL macro, which only accepts
  86 // literal strings: When the label stack frames generated by
  87 // AUTO_BASE_PROFILER_LABEL are sampled, no string copy needs to be made because
  88 // the profile buffer can just store the raw pointers to the literal strings.
  89 // Consequently, AUTO_BASE_PROFILER_LABEL frames take up considerably less space
  90 // in the profile buffer than AUTO_BASE_PROFILER_LABEL_DYNAMIC_* frames.
  91 #  define AUTO_BASE_PROFILER_LABEL_DYNAMIC_CSTR(label, categoryPair, cStr) \
  92     ::mozilla::baseprofiler::AutoProfilerLabel BASE_PROFILER_RAII(         \
  93         label, cStr,                                                       \
  94         ::mozilla::baseprofiler::ProfilingCategoryPair::categoryPair)
  95
  96 // Similar to AUTO_BASE_PROFILER_LABEL_DYNAMIC_CSTR, but takes an std::string.
  97 //
  98 // Note: The use of the Maybe<>s ensures the scopes for the dynamic string and
  99 // the AutoProfilerLabel are appropriate, while also not incurring the runtime
 100 // cost of the string assignment unless the profiler is active. Therefore,
 101 // unlike AUTO_BASE_PROFILER_LABEL and AUTO_BASE_PROFILER_LABEL_DYNAMIC_CSTR,
 102 // this macro doesn't push/pop a label when the profiler is inactive.
 103 #  define AUTO_BASE_PROFILER_LABEL_DYNAMIC_STRING(label, categoryPair, str) \
 104     Maybe<std::string> autoStr;                                             \
 105     Maybe<::mozilla::baseprofiler::AutoProfilerLabel> raiiObjectString;     \
 106     if (::mozilla::baseprofiler::profiler_is_active()) {                    \
 107       autoStr.emplace(str);                                                 \
 108       raiiObjectString.emplace(                                             \
 109           label, autoStr->c_str(),                                          \
 110           ::mozilla::baseprofiler::ProfilingCategoryPair::categoryPair);    \
 111     }
 112
 113 // Similar to AUTO_BASE_PROFILER_LABEL, but accepting a JSContext* parameter,
 114 // and a no-op if the profiler is disabled. Used to annotate functions for which
 115 // overhead in the range of nanoseconds is noticeable. It avoids overhead from
 116 // the TLS lookup because it can get the ProfilingStack from the JS context, and
 117 // avoids almost all overhead in the case where the profiler is disabled.
 118 #  define AUTO_BASE_PROFILER_LABEL_FAST(label, categoryPair, ctx)  \
 119     ::mozilla::baseprofiler::AutoProfilerLabel BASE_PROFILER_RAII( \
 120         ctx, label, nullptr,                                       \
 121         ::mozilla::baseprofiler::ProfilingCategoryPair::categoryPair)
 122
 123 // Similar to AUTO_BASE_PROFILER_LABEL_FAST, but also takes an extra string and
 124 // an additional set of flags. The flags parameter should carry values from the
 125 // ProfilingStackFrame::Flags enum.
 126 #  define AUTO_BASE_PROFILER_LABEL_DYNAMIC_FAST(label, dynamicString,     \
 127                                                 categoryPair, ctx, flags) \
 128     ::mozilla::baseprofiler::AutoProfilerLabel BASE_PROFILER_RAII(        \
 129         ctx, label, dynamicString,                                        \
 130         ::mozilla::baseprofiler::ProfilingCategoryPair::categoryPair, flags)
 131
 132 // This class creates a non-owning ProfilingStack reference. Objects of this
 133 // class are stack-allocated, and so exist within a thread, and are thus bounded
 134 // by the lifetime of the thread, which ensures that the references held can't
 135 // be used after the ProfilingStack is destroyed.
 136 class MOZ_RAII AutoProfilerLabel {
 137  public:
 138   // This is the AUTO_BASE_PROFILER_LABEL and AUTO_BASE_PROFILER_LABEL_DYNAMIC
 139   // variant.
 140   AutoProfilerLabel(const char* aLabel, const char* aDynamicString,
 141                     ProfilingCategoryPair aCategoryPair, uint32_t aFlags = 0) {
 142     // Get the ProfilingStack from TLS.
 143     Push(GetProfilingStack(), aLabel, aDynamicString, aCategoryPair, aFlags);
 144   }
 145
 146   void Push(ProfilingStack* aProfilingStack, const char* aLabel,
 147             const char* aDynamicString, ProfilingCategoryPair aCategoryPair,
 148             uint32_t aFlags = 0) {
 149     // This function runs both on and off the main thread.
 150
 151     mProfilingStack = aProfilingStack;
 152     if (mProfilingStack) {
 153       mProfilingStack->pushLabelFrame(aLabel, aDynamicString, this,
 154                                       aCategoryPair, aFlags);
 155     }
 156   }
 157
 158   ~AutoProfilerLabel() {
 159     // This function runs both on and off the main thread.
 160
 161     if (mProfilingStack) {
 162       mProfilingStack->pop();
 163     }
 164   }
 165
 166   MFBT_API static ProfilingStack* GetProfilingStack();
 167
 168  private:
 169   // We save a ProfilingStack pointer in the ctor so we don't have to redo the
 170   // TLS lookup in the dtor.
 171   ProfilingStack* mProfilingStack;
 172
 173  public:
 174   // See the comment on the definition in platform.cpp for details about this.
 175   static MOZ_THREAD_LOCAL(ProfilingStack*) sProfilingStack;
 176 };
 177
 178 }  // namespace mozilla::baseprofiler
 179
 180 #endif  // !MOZ_GECKO_PROFILER
 181
 182 #endif  // BaseProfilerLabels_h