base/profiler/profile_builder.h

   1 // Copyright 2019 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef BASE_PROFILER_PROFILE_BUILDER_H_
   6 #define BASE_PROFILER_PROFILE_BUILDER_H_
   7
   8 #include <memory>
   9 #include <vector>
  10
  11 #include "base/base_export.h"
  12 #include "base/profiler/frame.h"
  13 #include "base/profiler/metadata_recorder.h"
  14 #include "base/profiler/module_cache.h"
  15 #include "base/time/time.h"
  16
  17 namespace base {
  18
  19 // The ProfileBuilder interface allows the user to record profile information on
  20 // the fly in whatever format is desired. Functions are invoked by the profiler
  21 // on its own thread so must not block or perform expensive operations.
  22 class BASE_EXPORT ProfileBuilder {
  23  public:
  24   ProfileBuilder() = default;
  25
  26   ProfileBuilder(const ProfileBuilder&) = delete;
  27   ProfileBuilder& operator=(const ProfileBuilder&) = delete;
  28
  29   virtual ~ProfileBuilder() = default;
  30
  31   // Gets the ModuleCache to be used by the StackSamplingProfiler when looking
  32   // up modules from addresses.
  33   virtual ModuleCache* GetModuleCache() = 0;
  34
  35   // Records metadata to be associated with the current sample. To avoid
  36   // deadlock on locks taken by the suspended profiled thread, implementations
  37   // of this method must not execute any code that could take a lock, including
  38   // heap allocation or use of CHECK/DCHECK/LOG statements. Generally
  39   // implementations should simply atomically copy metadata state to be
  40   // associated with the sample.
  41   virtual void RecordMetadata(
  42       const MetadataRecorder::MetadataProvider& metadata_provider) {}
  43
  44   // Applies the specified metadata |item| to samples collected in the range
  45   // [period_start, period_end), iff the profile already captured execution that
  46   // covers that range entirely. This restriction avoids bias in the results
  47   // towards samples in the middle of the period, at the expense of excluding
  48   // periods overlapping the start or end of the profile. |period_end| must be
  49   // <= TimeTicks::Now().
  50   virtual void ApplyMetadataRetrospectively(
  51       TimeTicks period_start,
  52       TimeTicks period_end,
  53       const MetadataRecorder::Item& item) {}
  54
  55   // Adds the specified metadata |item| to |CallstackProfile::profile_metadata|.
  56   // |CallstackProfile::profile_metadata| stores metadata global to the profile.
  57   virtual void AddProfileMetadata(const MetadataRecorder::Item& item) {}
  58
  59   // Records a new set of frames. Invoked when sampling a sample completes.
  60   virtual void OnSampleCompleted(std::vector<Frame> frames,
  61                                  TimeTicks sample_timestamp) = 0;
  62
  63   // Finishes the profile construction with |profile_duration| and
  64   // |sampling_period|. Invoked when sampling a profile completes.
  65   virtual void OnProfileCompleted(TimeDelta profile_duration,
  66                                   TimeDelta sampling_period) = 0;
  67 };
  68
  69 }  // namespace base
  70
  71 #endif  // BASE_PROFILER_PROFILE_BUILDER_H_