Subversion Repositories QNX 8.QNX8 LLVM/Clang compiler suite

//===- llvm/Support/TimeProfiler.h - Hierarchical Time Profiler -*- C++ -*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

//

// This provides lightweight and dependency-free machinery to trace execution

// time around arbitrary code. Two API flavors are available.

//

// The primary API uses a RAII object to trigger tracing:

//

// \code

//   {

//     TimeTraceScope scope("my_event_name");

//     ...my code...

//   }

// \endcode

//

// If the code to be profiled does not have a natural lexical scope then

// it is also possible to start and end events with respect to an implicit

// per-thread stack of profiling entries:

//

// \code

//   timeTraceProfilerBegin("my_event_name");

//   ...my code...

//   timeTraceProfilerEnd();  // must be called on all control flow paths

// \endcode

//

// Time profiling entries can be given an arbitrary name and, optionally,

// an arbitrary 'detail' string. The resulting trace will include 'Total'

// entries summing the time spent for each name. Thus, it's best to choose

// names to be fairly generic, and rely on the detail field to capture

// everything else of interest.

//

// To avoid lifetime issues name and detail strings are copied into the event

// entries at their time of creation. Care should be taken to make string

// construction cheap to prevent 'Heisenperf' effects. In particular, the

// 'detail' argument may be a string-returning closure:

//

// \code

//   int n;

//   {

//     TimeTraceScope scope("my_event_name",

//                          [n]() { return (Twine("x=") + Twine(n)).str(); });

//     ...my code...

//   }

// \endcode

// The closure will not be called if tracing is disabled. Otherwise, the

// resulting string will be directly moved into the entry.

//

// The main process should begin with a timeTraceProfilerInitialize, and

// finish with timeTraceProfileWrite and timeTraceProfilerCleanup calls.

// Each new thread should begin with a timeTraceProfilerInitialize, and

// finish with a timeTraceProfilerFinishThread call.

//

// Timestamps come from std::chrono::stable_clock. Note that threads need

// not see the same time from that clock, and the resolution may not be

// the best available.

//

// Currently, there are a number of compatible viewers:

//  - chrome://tracing is the original chromium trace viewer.

//  - http://ui.perfetto.dev is the replacement for the above, under active

//    development by Google as part of the 'Perfetto' project.

//  - https://www.speedscope.app/ has also been reported as an option.

//

// Future work:

//  - Support akin to LLVM_DEBUG for runtime enable/disable of named tracing

//    families for non-debug builds which wish to support optional tracing.

//  - Evaluate the detail closures at profile write time to avoid

//    stringification costs interfering with tracing.

//

//===----------------------------------------------------------------------===//

#ifndef LLVM_SUPPORT_TIMEPROFILER_H

#define LLVM_SUPPORT_TIMEPROFILER_H

#include "llvm/ADT/STLFunctionalExtras.h"

#include "llvm/Support/Error.h"

namespace llvm {

class raw_pwrite_stream;

struct TimeTraceProfiler;

TimeTraceProfiler *getTimeTraceProfilerInstance();

/// Initialize the time trace profiler.

/// This sets up the global \p TimeTraceProfilerInstance

/// variable to be the profiler instance.

void timeTraceProfilerInitialize(unsigned TimeTraceGranularity,

                                 StringRef ProcName);

/// Cleanup the time trace profiler, if it was initialized.

void timeTraceProfilerCleanup();

/// Finish a time trace profiler running on a worker thread.

void timeTraceProfilerFinishThread();

/// Is the time trace profiler enabled, i.e. initialized?

inline bool timeTraceProfilerEnabled() {

  return getTimeTraceProfilerInstance() != nullptr;

}

/// Write profiling data to output stream.

/// Data produced is JSON, in Chrome "Trace Event" format, see

/// https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview

void timeTraceProfilerWrite(raw_pwrite_stream &OS);

/// Write profiling data to a file.

/// The function will write to \p PreferredFileName if provided, if not

/// then will write to \p FallbackFileName appending .time-trace.

/// Returns a StringError indicating a failure if the function is

/// unable to open the file for writing.

Error timeTraceProfilerWrite(StringRef PreferredFileName,

                             StringRef FallbackFileName);

/// Manually begin a time section, with the given \p Name and \p Detail.

/// Profiler copies the string data, so the pointers can be given into

/// temporaries. Time sections can be hierarchical; every Begin must have a

/// matching End pair but they can nest.

void timeTraceProfilerBegin(StringRef Name, StringRef Detail);

void timeTraceProfilerBegin(StringRef Name,

                            llvm::function_ref<std::string()> Detail);

/// Manually end the last time section.

void timeTraceProfilerEnd();

/// The TimeTraceScope is a helper class to call the begin and end functions

/// of the time trace profiler.  When the object is constructed, it begins

/// the section; and when it is destroyed, it stops it. If the time profiler

/// is not initialized, the overhead is a single branch.

struct TimeTraceScope {

  TimeTraceScope() = delete;

  TimeTraceScope(const TimeTraceScope &) = delete;

  TimeTraceScope &operator=(const TimeTraceScope &) = delete;

  TimeTraceScope(TimeTraceScope &&) = delete;

  TimeTraceScope &operator=(TimeTraceScope &&) = delete;

  TimeTraceScope(StringRef Name) {

    if (getTimeTraceProfilerInstance() != nullptr)

      timeTraceProfilerBegin(Name, StringRef(""));

  }

  TimeTraceScope(StringRef Name, StringRef Detail) {

    if (getTimeTraceProfilerInstance() != nullptr)

      timeTraceProfilerBegin(Name, Detail);

  }

  TimeTraceScope(StringRef Name, llvm::function_ref<std::string()> Detail) {

    if (getTimeTraceProfilerInstance() != nullptr)

      timeTraceProfilerBegin(Name, Detail);

  }

  ~TimeTraceScope() {

    if (getTimeTraceProfilerInstance() != nullptr)

      timeTraceProfilerEnd();

  }

};

} // end namespace llvm

#endif