base: Add blame context

base/trace_event/blame_context.h

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef BASE_TRACE_EVENT_BLAME_CONTEXT_H_
+#define BASE_TRACE_EVENT_BLAME_CONTEXT_H_
+
+#include <inttypes.h>
+
+#include "base/base_export.h"
+#include "base/macros.h"
+#include "base/trace_event/trace_log.h"
+
+namespace base {
+namespace trace_event {
+class TracedValue;
+}
+
+namespace trace_event {
+
+// A blame context represents a logical unit to which we want to attribute
+// different costs (e.g., CPU, network, or memory usage). An example of a blame
+// context is an <iframe> element on a web page. Different subsystems can
+// "enter" and "leave" blame contexts to indicate that they are doing work which
+// should be accounted against this blame context.
+//
+// A blame context can optionally have a parent context, forming a blame context
+// tree. When work is attributed to a particular blame context, it is considered
+// to count against all of that context's children too. This is useful when work
+// cannot be exactly attributed into a more specific context. For example,
+// Javascript garbage collection generally needs to inspect all objects on a
+// page instead looking at each <iframe> individually. In this case the work
+// should be attributed to a blame context which is the parent of all <iframe>
+// blame contexts.
+class BASE_EXPORT BlameContext
+    : public trace_event::TraceLog::EnabledStateObserver {
+ public:
+  // Construct a blame context belonging to the blame context tree |name|, using
+  // the tracing category |category|, identified by |id| from the |scope|
+  // namespace. |type| identifies the type of this object snapshot in the blame
+  // context tree. |parent_context| is the parent of this blame context or
+  // null. Note that all strings must have application lifetime.
+  //
+  // For example, a blame context which represents a specific <iframe> in a
+  // browser frame tree could be specified with:
+  //
+  //   category="blink",
+  //   name="FrameTree",
+  //   type="IFrame",
+  //   scope="IFrameIdentifier",
+  //   id=1234.
+  //
+  // Each <iframe> blame context could have another <iframe> context as a
+  // parent, or a top-level context which represents the entire browser:
+  //
+  //   category="blink",
+  //   name="FrameTree",
+  //   type="Browser",
+  //   scope="BrowserIdentifier",
+  //   id=1.
+  //
+  // Note that the |name| property is identical, signifying that both context
+  // types are part of the same tree.
+  //
+  BlameContext(const char* category,
+               const char* name,
+               const char* type,
+               const char* scope,
+               int64_t id,
+               const BlameContext* parent_context);
+  ~BlameContext() override;
+
+  // Initialize the blame context, automatically taking a snapshot if tracing is
+  // enabled. Must be called before any other methods on this class.
+  void Initialize();
+
+  // Indicate that the current thread is now doing work which should count
+  // against this blame context.
+  void Enter();
+
+  // Leave and stop doing work for a previously entered blame context. If
+  // another blame context belongin to the same tree was entered prior to this
+  // one, it becomes the active blame context for this thread again.
+  void Leave();
+
+  // Record a snapshot of the blame context. This is normally only needed if a
+  // blame context subclass defines custom properties (see AsValueInto) and one
+  // or more of those properties have changed.
+  void TakeSnapshot();
+
+  const char* category() const { return category_; }
+  const char* name() const { return name_; }
+  const char* type() const { return type_; }
+  const char* scope() const { return scope_; }
+  int64_t id() const { return id_; }
+
+  // trace_event::TraceLog::EnabledStateObserver implementation:
+  void OnTraceLogEnabled() override;
+  void OnTraceLogDisabled() override;
+
+ protected:
+  // Serialize the properties of this blame context into |state|. Subclasses can
+  // override this method to record additional properties (e.g, the URL for an
+  // <iframe> blame context). Note that an overridden implementation must still
+  // call this base method.
+  virtual void AsValueInto(trace_event::TracedValue* state);
+
+ private:
+  bool WasInitialized() const;
+
+  // The following string pointers have application lifetime.
+  const char* category_;
+  const char* name_;
+  const char* type_;
+  const char* scope_;
+  const int64_t id_;
+
+  const char* parent_scope_;
+  const int64_t parent_id_;
+
+  const unsigned char* category_group_enabled_;
+
+  DISALLOW_COPY_AND_ASSIGN(BlameContext);
+};
+
+}  // namespace trace_event
+}  // namespace base
+
+#endif  // BASE_TRACE_EVENT_BLAME_CONTEXT_H_