Make NetLog take in callbacks that return Values

net/base/net_log.h

 // Copyright (c) 2012 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 NET_BASE_NET_LOG_H_
 #define NET_BASE_NET_LOG_H_
 #pragma once
 
 #include <string>
 
 #include "base/basictypes.h"
+#include "base/callback_forward.h"
 #include "base/compiler_specific.h"
 #include "base/memory/ref_counted.h"
+#include "base/memory/scoped_ptr.h"
 #include "net/base/net_export.h"
 
 namespace base {
+class DictionaryValue;
 class TimeTicks;
 class Value;
 }
 
 namespace net {
 
 // NetLog is the destination for log messages generated by the network stack.
 // Each log message has a "source" field which identifies the specific entity
 // that generated the message (for example, which URLRequest or which
 // SocketStream).
 //
 // To avoid needing to pass in the "source ID" to the logging functions, NetLog
 // is usually accessed through a BoundNetLog, which will always pass in a
 // specific source ID.
 //
+// All NetLog methods must be thread-safe.
 class NET_EXPORT NetLog {
  public:
   enum EventType {
 #define EVENT_TYPE(label) TYPE_ ## label,
 #include "net/base/net_log_event_type_list.h"
 #undef EVENT_TYPE
     EVENT_COUNT
   };
 
   // The 'phase' of an event trace (whether it marks the beginning or end
   // of an event.).
   enum EventPhase {
     PHASE_NONE,
     PHASE_BEGIN,
     PHASE_END,
   };
 
   // The "source" identifies the entity that generated the log message.
   enum SourceType {
 #define SOURCE_TYPE(label) SOURCE_ ## label,
 #include "net/base/net_log_source_type_list.h"
 #undef SOURCE_TYPE
     SOURCE_COUNT
   };
 
+  // Specifies the granularity of events that should be emitted to the log.
+  enum LogLevel {
+    // Log everything possible, even if it is slow and memory expensive.
+    // Includes logging of transferred bytes.
+    LOG_ALL,
+
+    // Log all events, but do not include the actual transferred bytes as
+    // parameters for bytes sent/received events.
+    LOG_ALL_BUT_BYTES,
+
+    // Only log events which are cheap, and don't consume much memory.
+    LOG_BASIC,
+  };
+
+  // A callback function that return a Value representation of the parameters
+  // associated with an event.  If called, it will be called synchonously,
+  // so it need not have owning references.  May be called more than once, or
+  // not at all.  May return NULL.
+  typedef base::Callback<base::Value*(LogLevel)> ParametersCallback;
+
   // Identifies the entity that generated this log. The |id| field should
   // uniquely identify the source, and is used by log observers to infer
   // message groupings. Can use NetLog::NextID() to create unique IDs.
   struct NET_EXPORT Source {
     static const uint32 kInvalidId = 0;
 
     Source() : type(SOURCE_NONE), id(kInvalidId) {}
     Source(SourceType type, uint32 id) : type(type), id(id) {}
     bool is_valid() const { return id != kInvalidId; }
 
-    // The caller takes ownership of the returned Value*.
+    // Obsolete.  The caller takes ownership of the returned Value*.
+    // TODO(mmenke):  Remove this.
     base::Value* ToValue() const;
 
+    // Adds the source to a DictionaryValue containing event parameters,
+    // using the name "source_dependency".
+    void AddToEventParameters(base::DictionaryValue* event_params) const;
+
+    // Returns a callback that returns a dictionary with a single entry
+    // named "source_dependecy" that describes |this|.
+    ParametersCallback ToEventParametersCallback() const;
+
+    // Attempts to extract a Source from a set of event parameters.  Returns
+    // true and writes the result to |source| on success.  Returns false and
+    // makes |source| an invalid source on failure.
+    // TODO(mmenke):  Long term, we want to remove this.
+    static bool FromEventParameters(base::Value* event_params, Source* source);
+
     SourceType type;
     uint32 id;
   };
 
   // Base class for associating additional parameters with an event. Log
   // observers need to know what specific derivations of EventParameters a
   // particular EventType uses, in order to get at the individual components.
+  // This class is obsolete.  New code should use ParametersCallbacks.
+  // TODO(mmenke):  Update users of this class and get rid of it.
   class NET_EXPORT EventParameters
       : public base::RefCountedThreadSafe<EventParameters> {
    public:
     EventParameters() {}
 
     // Serializes the parameters to a Value tree. This is intended to be a
     // lossless conversion, which is used to serialize the parameters to JSON.
     // The caller takes ownership of the returned Value*.
     virtual base::Value* ToValue() const = 0;
 
    protected:
     virtual ~EventParameters() {}
 
    private:
     friend class base::RefCountedThreadSafe<EventParameters>;
 
     DISALLOW_COPY_AND_ASSIGN(EventParameters);
   };
 
-  // Specifies the granularity of events that should be emitted to the log.
-  enum LogLevel {
-    // Log everything possible, even if it is slow and memory expensive.
-    // Includes logging of transferred bytes.
-    LOG_ALL,
+  class NET_EXPORT Entry {
+   public:
+    Entry(EventType type,
+          Source source,
+          EventPhase phase,
+          const ParametersCallback* parameters_callback,
+          LogLevel log_level);
+    ~Entry();
 
-    // Log all events, but do not include the actual transferred bytes as
-    // parameters for bytes sent/received events.
-    LOG_ALL_BUT_BYTES,
+    EventType type() const { return type_; }
+    Source source() const { return source_; }
+    EventPhase phase() const { return phase_; }
 
-    // Only log events which are cheap, and don't consume much memory.
-    LOG_BASIC,
+    // Serializes the specified event to a Value.  The Value also includes the
+    // current time.  Caller takes ownership of returned Value.
+    base::Value* ToValue() const;
+
+    // Returns the parameters as a Value.  Returns NULL if there are no
+    // parameters.  Caller takes ownership of returned Value.
+    base::Value* ParametersToValue() const;
+
+   private:
+    const EventType type_;
+    const Source source_;
+    const EventPhase phase_;
+    const ParametersCallback* parameters_callback_;
+
+    // Log level when the event occurred.
+    const LogLevel log_level_;
+
+    // It is not safe to copy this class, since |parameters_callback_| may
+    // include pointers that become stale immediately after the event is added,
+    // even if the code were modified to keep its own copy of the callback.
+    DISALLOW_COPY_AND_ASSIGN(Entry);
   };
 
   // An observer, that must ensure its own thread safety, for events
   // being added to a NetLog.
   class NET_EXPORT ThreadSafeObserver {
    public:
     // Constructs an observer that wants to see network events, with
     // the specified minimum event granularity.  A ThreadSafeObserver can only
     // observe a single NetLog at a time.
     //
@@ skipping 11 matching lines @@
     // Returns the NetLog we are currently watching, if any.  Returns NULL
     // otherwise.
     NetLog* net_log() const;
 
     // This method will be called on the thread that the event occurs on.  It
     // is the responsibility of the observer to handle it in a thread safe
     // manner.
     //
     // It is illegal for an Observer to call any NetLog or
     // NetLog::Observer functions in response to a call to OnAddEntry.
-    //
-    // |type| - The type of the event.
-    // |time| - The time when the event occurred.
-    // |source| - The source that generated the event.
-    // |phase| - An optional parameter indicating whether this is the start/end
-    //           of an action.
-    // |params| - Optional (may be NULL) parameters for this event.
-    //            The specific subclass of EventParameters is defined
-    //            by the contract for events of this |type|.
-    // TODO(eroman): Take a scoped_refptr<EventParameters> instead.
-    virtual void OnAddEntry(EventType type,
-                            const base::TimeTicks& time,
-                            const Source& source,
-                            EventPhase phase,
-                            EventParameters* params) = 0;
+    virtual void OnAddEntry(const Entry& entry) = 0;
 
    protected:
     virtual ~ThreadSafeObserver();
 
    private:
     friend class NetLog;
 
     // Both of these values are only modified by the NetLog.
     LogLevel log_level_;
     NetLog* net_log_;
 
     DISALLOW_COPY_AND_ASSIGN(ThreadSafeObserver);
   };
 
   NetLog() {}
   virtual ~NetLog() {}
 
   // Emits a global event to the log stream, with its own unique source ID.
+  void AddGlobalEntry(EventType type);
+  void AddGlobalEntry(EventType type,
+                      const NetLog::ParametersCallback& parameters_callback);
+
+  // Older, obsolete version of above functions.  Use the ParametersCallback
+  // versions instead.
+  // TODO(mmenke):  Remove this.
   void AddGlobalEntry(EventType type,
                       const scoped_refptr<EventParameters>& params);
 
-  // Returns a unique ID which can be used as a source ID.
+  // Returns a unique ID which can be used as a source ID.  All returned IDs
+  // will be unique and greater than 0.
   virtual uint32 NextID() = 0;
 
   // Returns the logging level for this NetLog. This is used to avoid computing
   // and saving expensive log entries.
   virtual LogLevel GetLogLevel() const = 0;
 
   // Adds an observer and sets its log level.  The observer must not be
   // watching any NetLog, including this one, when this is called.
   //
   // Typical observers should specify LOG_BASIC.
@@ skipping 33 matching lines @@
   // Returns a C-String symbolic name for |source_type|.
   static const char* SourceTypeToString(SourceType source_type);
 
   // Returns a dictionary that maps source type symbolic names to their enum
   // values.  Caller takes ownership of the returned Value.
   static base::Value* GetSourceTypesAsValue();
 
   // Returns a C-String symbolic name for |event_phase|.
   static const char* EventPhaseToString(EventPhase event_phase);
 
-  // Serializes the specified event to a DictionaryValue.
-  // If |use_strings| is true, uses strings rather than numeric ids.
-  static base::Value* EntryToDictionaryValue(NetLog::EventType type,
-                                             const base::TimeTicks& time,
-                                             const NetLog::Source& source,
-                                             NetLog::EventPhase phase,
-                                             NetLog::EventParameters* params,
-                                             bool use_strings);
+  // Returns true if |log_level| indicates the actual bytes transferred should
+  // be logged.  This is only the case when |log_level| is LOG_ALL.
+  static bool IsLoggingBytes(LogLevel log_level);
+
+  // Returns true if |log_level| indicates that all events should be logged,
+  // including frequently occuring ones that may impact performances.
+  // This is the case when |log_level| is LOG_ALL or LOG_ALL_BUT_BYTES.
+  static bool IsLoggingAllEvents(LogLevel log_level);
+
+  // Creates a ParametersCallback that encapsulates a single integer.
+  // Warning: |name| must remain valid for the life of the callback.
+  static ParametersCallback IntegerCallback(const char* name, int value);
 
  protected:
-  // This is the internal function used by AddGlobalEntry and BoundNetLogs.
-  virtual void AddEntry(
-      EventType type,
-      const Source& source,
-      EventPhase phase,
-      const scoped_refptr<NetLog::EventParameters>& params) = 0;
+  // Child classes should respond to the new entry here.  This includes
+  // creating the Entry object and alerting their observers.
+  virtual void OnAddEntry(const Entry& entry) = 0;
 
   // Subclasses must call these in the corresponding functions to set an
   // observer's |net_log_| and |log_level_| values.
   void OnAddObserver(ThreadSafeObserver* observer, LogLevel log_level);
   void OnSetObserverLogLevel(ThreadSafeObserver* observer,
                              LogLevel log_level);
   void OnRemoveObserver(ThreadSafeObserver* observer);
 
  private:
   friend class BoundNetLog;
 
+  void AddEntry(EventType type,
+                const Source& source,
+                EventPhase phase,
+                const NetLog::ParametersCallback* parameters_callback);
+
   DISALLOW_COPY_AND_ASSIGN(NetLog);
 };
 
 // Helper that binds a Source to a NetLog, and exposes convenience methods to
 // output log messages without needing to pass in the source.
 class NET_EXPORT BoundNetLog {
  public:
   BoundNetLog() : net_log_(NULL) {}
 
-  // Convenience methods that call through to the NetLog, passing in the
-  // currently bound source.
+  // Add a log entry to the NetLog for the bound source.
+  void AddEntry(NetLog::EventType type, NetLog::EventPhase phase) const;
+  void AddEntry(NetLog::EventType type,
+                NetLog::EventPhase phase,
+                const NetLog::ParametersCallback& get_parameters) const;
+
+  // Convenience methods that call AddEntry with a fixed "capture phase"
+  // (begin, end, or none).
+  void BeginEvent(NetLog::EventType type) const;
+  void BeginEvent(NetLog::EventType type,
+                  const NetLog::ParametersCallback& get_parameters) const;
+
+  void EndEvent(NetLog::EventType type) const;
+  void EndEvent(NetLog::EventType type,
+                const NetLog::ParametersCallback& get_parameters) const;
+
+  void AddEvent(NetLog::EventType type) const;
+  void AddEvent(NetLog::EventType type,
+                const NetLog::ParametersCallback& get_parameters) const;
+
+  // Obsolete versions of the above functions.
+  // Use the ParametersCallback versions of these functions instead.
+  // TODO(mmenke):  Remove these.
   void AddEntry(NetLog::EventType type,
                 NetLog::EventPhase phase,
                 const scoped_refptr<NetLog::EventParameters>& params) const;
-
-  // Convenience methods that call through to the NetLog, passing in the
-  // currently bound source, current time, and a fixed "capture phase"
-  // (begin, end, or none).
   void AddEvent(NetLog::EventType event_type,
                 const scoped_refptr<NetLog::EventParameters>& params) const;
   void BeginEvent(NetLog::EventType event_type,
                   const scoped_refptr<NetLog::EventParameters>& params) const;
   void EndEvent(NetLog::EventType event_type,
                 const scoped_refptr<NetLog::EventParameters>& params) const;
 
   // Just like AddEvent, except |net_error| is a net error code.  A parameter
   // called "net_error" with the indicated value will be recorded for the event.
   // |net_error| must be negative, and not ERR_IO_PENDING, as it's not a true
   // error.
   void AddEventWithNetErrorCode(NetLog::EventType event_type,
                                 int net_error) const;
 
   // Just like EndEvent, except |net_error| is a net error code.  If it's
   // negative, a parameter called "net_error" with a value of |net_error| is
   // associated with the event.  Otherwise, the end event has no parameters.
   // |net_error| must not be ERR_IO_PENDING, as it's not a true error.
   void EndEventWithNetErrorCode(NetLog::EventType event_type,
                                 int net_error) const;
 
   // Logs a byte transfer event to the NetLog.  Determines whether to log the
   // received bytes or not based on the current logging level.
   void AddByteTransferEvent(NetLog::EventType event_type,
                             int byte_count, const char* bytes) const;
 
   NetLog::LogLevel GetLogLevel() const;
 
-  // Returns true if the log level is LOG_ALL.
+  // Shortcut for NetLog::IsLoggingBytes(this->GetLogLevel()).
   bool IsLoggingBytes() const;
 
-  // Returns true if the log level is LOG_ALL or LOG_ALL_BUT_BYTES.
+  // Shortcut for NetLog::IsLoggingAllEvents(this->GetLogLevel()).
   bool IsLoggingAllEvents() const;
 
   // Helper to create a BoundNetLog given a NetLog and a SourceType. Takes care
   // of creating a unique source ID, and handles the case of NULL net_log.
   static BoundNetLog Make(NetLog* net_log, NetLog::SourceType source_type);
 
   const NetLog::Source& source() const { return source_; }
   NetLog* net_log() const { return net_log_; }
 
  private:
   BoundNetLog(const NetLog::Source& source, NetLog* net_log)
       : source_(source), net_log_(net_log) {
   }
 
   NetLog::Source source_;
   NetLog* net_log_;
 };
 
+// All the classes below are obsolete.  New code should use ParametersCallbacks.
+// TODO(mmenke):  Update users these classes and get rid of them.
+
 // NetLogStringParameter is a subclass of EventParameters that encapsulates a
 // single std::string parameter.
 class NET_EXPORT NetLogStringParameter : public NetLog::EventParameters {
  public:
   // |name| must be a string literal.
   NetLogStringParameter(const char* name, const std::string& value);
 
   const std::string& value() const {
     return value_;
   }
@@ skipping 45 matching lines @@
   virtual base::Value* ToValue() const OVERRIDE;
 
  protected:
   virtual ~NetLogSourceParameter() {}
 
  private:
   const char* name_;
   const NetLog::Source value_;
 };
 
-// ScopedNetLogEvent logs a begin event on creation, and the corresponding end
-// event on destruction.
-class NET_EXPORT_PRIVATE ScopedNetLogEvent {
- public:
-  ScopedNetLogEvent(const BoundNetLog& net_log,
-                    NetLog::EventType event_type,
-                    const scoped_refptr<NetLog::EventParameters>& params);
-
-  ~ScopedNetLogEvent();
-
-  // Sets the parameters that will logged on object destruction.  Can be called
-  // at most once for a given ScopedNetLogEvent object.  If not called, the end
-  // event will have no parameters.
-  void SetEndEventParameters(
-      const scoped_refptr<NetLog::EventParameters>& end_event_params);
-
-  const BoundNetLog& net_log() const;
-
- private:
-  BoundNetLog net_log_;
-  const NetLog::EventType event_type_;
-  scoped_refptr<NetLog::EventParameters> end_event_params_;
-};
-
 }  // namespace net
 
 #endif  // NET_BASE_NET_LOG_H_