chromium/base/profiler/stack_sampling_profiler.h

// Copyright 2015 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef BASE_PROFILER_STACK_SAMPLING_PROFILER_H_
#define BASE_PROFILER_STACK_SAMPLING_PROFILER_H_

#include <memory>
#include <optional>
#include <vector>

#include "base/base_export.h"
#include "base/functional/callback.h"
#include "base/profiler/profile_builder.h"
#include "base/profiler/sampling_profiler_thread_token.h"
#include "base/synchronization/waitable_event.h"
#include "base/threading/platform_thread.h"
#include "base/time/time.h"

namespace base {

class Unwinder;
class StackSampler;
class StackSamplerTestDelegate;

// StackSamplingProfiler periodically stops a thread to sample its stack, for
// the purpose of collecting information about which code paths are
// executing. This information is used in aggregate by UMA to identify hot
// and/or janky code paths.
//
// Sample StackSamplingProfiler usage:
//
//   // Create and customize params as desired.
//   base::StackSamplingProfiler::SamplingParams params;
//
//   // Create a ProfileBuilder subclass to process the profiles.
//   class ProfileBuilder : public base::ProfileBuilder {...}
//
//   // Then create the profiler:
//   base::StackSamplingProfiler profiler(
//       GetSamplingProfilerCurrentThreadToken(),
//       params,
//       std::make_unique<ProfileBuilder>(...));
//
//   // On Android the caller also must provide a factory function for creating
//   // its core stack unwinders. See the ThreadProfiler implementation for an
//   // example of how to do this.
//   base::StackSamplingProfiler profiler(
//       GetSamplingProfilerCurrentThreadToken(),
//       params,
//       std::make_unique<ProfileBuilder>(...),
//       core_unwinders_factory);
//
//   // Then start the profiling.
//   profiler.Start();
//
//   // ... work being done on the target thread here ...
//
//   // Optionally stop collection before complete per params.
//   profiler.Stop();
//
// The default SamplingParams causes stacks to be recorded in a single profile
// at a 10Hz interval for a total of 30 seconds. All of these parameters may be
// altered as desired.
//
// When a call stack profile is complete, or the profiler is stopped,
// ProfileBuilder's OnProfileCompleted function is called from a thread created
// by the profiler.
class BASE_EXPORT StackSamplingProfiler { … };

}  // namespace base

#endif  // BASE_PROFILER_STACK_SAMPLING_PROFILER_H_