tor-browser

DecoderDoctorLogger.h (20854B)

---

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim:set ts=2 sw=2 sts=2 et cindent: */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef DecoderDoctorLogger_h_
#define DecoderDoctorLogger_h_

#include "DDLogCategory.h"
#include "DDLogValue.h"
#include "DDLoggedTypeTraits.h"
#include "mozilla/Atomics.h"
#include "mozilla/MozPromise.h"
#include "mozilla/NonDereferenceable.h"
#include "nsString.h"

namespace mozilla {

// Main class used to capture log messages from the media stack, and to
// retrieve processed messages associated with an HTMLMediaElement.
//
// The logging APIs are designed to work as fast as possible (in most cases
// only checking a couple of atomic variables, and not allocating memory), so
// as not to introduce perceptible latency.
// Consider using DDLOG...() macros, and IsDDLoggingEnabled(), to avoid any
// unneeded work when logging is not enabled.
//
// Structural logging messages are used to determine when objects are created
// and destroyed, and to link objects that depend on each other, ultimately
// tying groups of objects and their messages to HTMLMediaElement objects.
//
// A separate thread processes log messages, and can asynchronously retrieve
// processed messages that correspond to a given HTMLMediaElement.
// That thread is also responsible for removing dated messages, so as not to
// take too much memory.
class DecoderDoctorLogger {
public:
 // Called by nsLayoutStatics::Initialize() before any other media work.
 // Pre-enables logging if MOZ_LOG requires DDLogger.
 static void Init();

 // Is logging currently enabled? This is tested anyway in all public `Log...`
 // functions, but it may be used to prevent logging-only work in clients.
 static inline bool IsDDLoggingEnabled() {
   return MOZ_UNLIKELY(static_cast<LogState>(sLogState) == scEnabled);
 }

 // Shutdown logging. This will prevent more messages to be queued, but the
 // already-queued messages may still get processed.
 static void ShutdownLogging() { sLogState = scShutdown; }

 // Something went horribly wrong, stop all logging and log processing.
 static void Panic(const char* aReason) {
   PanicInternal(aReason, /* aDontBlock */ false);
 }

 // Logging functions.
 //
 // All logging functions take:
 // - The object that produces the message, either as a template type (for
 //   which a specialized DDLoggedTypeTraits exists), or a pointer and a type
 //   name (needed for inner classes that cannot specialize
 //   DDLoggedTypeTraits.)
 // - A DDLogCategory defining the type of log message; some are used
 //   internally for capture the lifetime and linking of C++ objects, others
 //   are used to split messages into different domains.
 // - A label (string literal).
 // - An optional Variant value, see DDLogValue for the accepted types.
 //
 // The following `EagerLog...` functions always cause their arguments to be
 // pre-evaluated even if logging is disabled, in which case runtime could be
 // wasted. Consider using `DDLOG...` macros instead, or test
 // `IsDDLoggingEnabled()` first.

 template <typename Value>
 static void EagerLogValue(const char* aSubjectTypeName,
                           const void* aSubjectPointer,
                           DDLogCategory aCategory, const char* aLabel,
                           Value&& aValue) {
   Log(aSubjectTypeName, aSubjectPointer, aCategory, aLabel,
       DDLogValue{std::forward<Value>(aValue)});
 }

 template <typename Subject, typename Value>
 static void EagerLogValue(const Subject* aSubject, DDLogCategory aCategory,
                           const char* aLabel, Value&& aValue) {
   EagerLogValue(DDLoggedTypeTraits<Subject>::Name(), aSubject, aCategory,
                 aLabel, std::forward<Value>(aValue));
 }

 // EagerLogValue that can explicitly take strings, as the templated function
 // above confuses Variant when forwarding string literals.
 static void EagerLogValue(const char* aSubjectTypeName,
                           const void* aSubjectPointer,
                           DDLogCategory aCategory, const char* aLabel,
                           const char* aValue) {
   Log(aSubjectTypeName, aSubjectPointer, aCategory, aLabel,
       DDLogValue{aValue});
 }

 template <typename Subject>
 static void EagerLogValue(const Subject* aSubject, DDLogCategory aCategory,
                           const char* aLabel, const char* aValue) {
   EagerLogValue(DDLoggedTypeTraits<Subject>::Name(), aSubject, aCategory,
                 aLabel, aValue);
 }

 static void EagerLogPrintf(const char* aSubjectTypeName,
                            const void* aSubjectPointer,
                            DDLogCategory aCategory, const char* aLabel,
                            const char* aString) {
   Log(aSubjectTypeName, aSubjectPointer, aCategory, aLabel,
       DDLogValue{nsCString{aString}});
 }

 template <typename... Args>
 static void EagerLogPrintf(const char* aSubjectTypeName,
                            const void* aSubjectPointer,
                            DDLogCategory aCategory, const char* aLabel,
                            const char* aFormat, Args&&... aArgs) {
   Log(aSubjectTypeName, aSubjectPointer, aCategory, aLabel,
       DDLogValue{
           nsCString{nsPrintfCString(aFormat, std::forward<Args>(aArgs)...)}});
 }

 template <typename Subject>
 static void EagerLogPrintf(const Subject* aSubject, DDLogCategory aCategory,
                            const char* aLabel, const char* aString) {
   EagerLogPrintf(DDLoggedTypeTraits<Subject>::Name(), aSubject, aCategory,
                  aLabel, aString);
 }

 template <typename Subject, typename... Args>
 static void EagerLogPrintf(const Subject* aSubject, DDLogCategory aCategory,
                            const char* aLabel, const char* aFormat,
                            Args&&... aArgs) {
   EagerLogPrintf(DDLoggedTypeTraits<Subject>::Name(), aSubject, aCategory,
                  aLabel, aFormat, std::forward<Args>(aArgs)...);
 }

 static void MozLogPrintf(const char* aSubjectTypeName,
                          const void* aSubjectPointer,
                          const LogModule* aLogModule, LogLevel aLogLevel,
                          const char* aString) {
   Log(aSubjectTypeName, aSubjectPointer, CategoryForMozLogLevel(aLogLevel),
       aLogModule->Name(),  // LogModule name as label.
       DDLogValue{nsCString{aString}});
   MOZ_LOG(aLogModule, aLogLevel,
           ("%s[%p] %s", aSubjectTypeName, aSubjectPointer, aString));
 }

 template <typename... Args>
 static void MozLogPrintf(const char* aSubjectTypeName,
                          const void* aSubjectPointer,
                          const LogModule* aLogModule, LogLevel aLogLevel,
                          const char* aFormat, Args&&... aArgs) {
   nsCString printed = nsPrintfCString(aFormat, std::forward<Args>(aArgs)...);
   Log(aSubjectTypeName, aSubjectPointer, CategoryForMozLogLevel(aLogLevel),
       aLogModule->Name(),  // LogModule name as label.
       DDLogValue{printed});
   MOZ_LOG(aLogModule, aLogLevel,
           ("%s[%p] %s", aSubjectTypeName, aSubjectPointer, printed.get()));
 }

 template <typename Subject>
 static void MozLogPrintf(const Subject* aSubject, const LogModule* aLogModule,
                          LogLevel aLogLevel, const char* aString) {
   MozLogPrintf(DDLoggedTypeTraits<Subject>::Name(), aSubject, aLogModule,
                aLogLevel, aString);
 }

 template <typename Subject, typename... Args>
 static void MozLogPrintf(const Subject* aSubject, const LogModule* aLogModule,
                          LogLevel aLogLevel, const char* aFormat,
                          Args&&... aArgs) {
   MozLogPrintf(DDLoggedTypeTraits<Subject>::Name(), aSubject, aLogModule,
                aLogLevel, aFormat, std::forward<Args>(aArgs)...);
 }

 // Special logging functions. Consider using DecoderDoctorLifeLogger to
 // automatically capture constructions & destructions.

 static void LogConstruction(const char* aSubjectTypeName,
                             const void* aSubjectPointer) {
   Log(aSubjectTypeName, aSubjectPointer, DDLogCategory::_Construction, "",
       DDLogValue{DDNoValue{}});
 }

 static void LogConstructionAndBase(const char* aSubjectTypeName,
                                    const void* aSubjectPointer,
                                    const char* aBaseTypeName,
                                    const void* aBasePointer) {
   Log(aSubjectTypeName, aSubjectPointer, DDLogCategory::_DerivedConstruction,
       "", DDLogValue{DDLogObject{aBaseTypeName, aBasePointer}});
 }

 template <typename B>
 static void LogConstructionAndBase(const char* aSubjectTypeName,
                                    const void* aSubjectPointer,
                                    const B* aBase) {
   Log(aSubjectTypeName, aSubjectPointer, DDLogCategory::_DerivedConstruction,
       "", DDLogValue{DDLogObject{DDLoggedTypeTraits<B>::Name(), aBase}});
 }

 template <typename Subject>
 static void LogConstruction(NonDereferenceable<const Subject> aSubject) {
   using Traits = DDLoggedTypeTraits<Subject>;
   if (!Traits::HasBase::value) {
     Log(DDLoggedTypeTraits<Subject>::Name(),
         reinterpret_cast<const void*>(aSubject.value()),
         DDLogCategory::_Construction, "", DDLogValue{DDNoValue{}});
   } else {
     Log(DDLoggedTypeTraits<Subject>::Name(),
         reinterpret_cast<const void*>(aSubject.value()),
         DDLogCategory::_DerivedConstruction, "",
         DDLogValue{DDLogObject{
             DDLoggedTypeTraits<typename Traits::BaseType>::Name(),
             reinterpret_cast<const void*>(
                 NonDereferenceable<const typename Traits::BaseType>(aSubject)
                     .value())}});
   }
 }

 template <typename Subject>
 static void LogConstruction(const Subject* aSubject) {
   LogConstruction(NonDereferenceable<const Subject>(aSubject));
 }

 static void LogDestruction(const char* aSubjectTypeName,
                            const void* aSubjectPointer) {
   Log(aSubjectTypeName, aSubjectPointer, DDLogCategory::_Destruction, "",
       DDLogValue{DDNoValue{}});
 }

 template <typename Subject>
 static void LogDestruction(NonDereferenceable<const Subject> aSubject) {
   Log(DDLoggedTypeTraits<Subject>::Name(),
       reinterpret_cast<const void*>(aSubject.value()),
       DDLogCategory::_Destruction, "", DDLogValue{DDNoValue{}});
 }

 template <typename Subject>
 static void LogDestruction(const Subject* aSubject) {
   LogDestruction(NonDereferenceable<const Subject>(aSubject));
 }

 template <typename P, typename C>
 static void LinkParentAndChild(const P* aParent, const char* aLinkName,
                                const C* aChild) {
   if (aChild) {
     Log(DDLoggedTypeTraits<P>::Name(), aParent, DDLogCategory::_Link,
         aLinkName,
         DDLogValue{DDLogObject{DDLoggedTypeTraits<C>::Name(), aChild}});
   }
 }

 template <typename C>
 static void LinkParentAndChild(const char* aParentTypeName,
                                const void* aParentPointer,
                                const char* aLinkName, const C* aChild) {
   if (aChild) {
     Log(aParentTypeName, aParentPointer, DDLogCategory::_Link, aLinkName,
         DDLogValue{DDLogObject{DDLoggedTypeTraits<C>::Name(), aChild}});
   }
 }

 template <typename P>
 static void LinkParentAndChild(const P* aParent, const char* aLinkName,
                                const char* aChildTypeName,
                                const void* aChildPointer) {
   if (aChildPointer) {
     Log(DDLoggedTypeTraits<P>::Name(), aParent, DDLogCategory::_Link,
         aLinkName, DDLogValue{DDLogObject{aChildTypeName, aChildPointer}});
   }
 }

 template <typename C>
 static void UnlinkParentAndChild(const char* aParentTypeName,
                                  const void* aParentPointer,
                                  const C* aChild) {
   if (aChild) {
     Log(aParentTypeName, aParentPointer, DDLogCategory::_Unlink, "",
         DDLogValue{DDLogObject{DDLoggedTypeTraits<C>::Name(), aChild}});
   }
 }

 template <typename P, typename C>
 static void UnlinkParentAndChild(const P* aParent, const C* aChild) {
   if (aChild) {
     Log(DDLoggedTypeTraits<P>::Name(), aParent, DDLogCategory::_Unlink, "",
         DDLogValue{DDLogObject{DDLoggedTypeTraits<C>::Name(), aChild}});
   }
 }

 // Retrieval functions.

 // Enable logging, if not done already. No effect otherwise.
 static void EnableLogging();

 using LogMessagesPromise =
     MozPromise<nsCString, nsresult, /* IsExclusive = */ true>;

 // Retrieve all messages related to a given HTMLMediaElement object.
 // This call will trigger a processing run (to ensure the most recent data
 // will be returned), and the returned promise will be resolved with all
 // relevant log messages and object lifetimes in a JSON string.
 // The first call will enable logging, until shutdown.
 static RefPtr<LogMessagesPromise> RetrieveMessages(
     const dom::HTMLMediaElement* aMediaElement);

private:
 // If logging is not enabled yet, initiate it, return true.
 // If logging has been shutdown, don't start it, return false.
 // Otherwise return true.
 static bool EnsureLogIsEnabled();

 // Note that this call may block while the state is scEnabling;
 // set aDontBlock to true to avoid blocking, most importantly when the
 // caller is the one doing the enabling, this would cause an endless loop.
 static void PanicInternal(const char* aReason, bool aDontBlock);

 static void Log(const char* aSubjectTypeName, const void* aSubjectPointer,
                 DDLogCategory aCategory, const char* aLabel,
                 DDLogValue&& aValue);

 static void Log(const char* aSubjectTypeName, const void* aSubjectPointer,
                 const LogModule* aLogModule, LogLevel aLogLevel,
                 DDLogValue&& aValue);

 static DDLogCategory CategoryForMozLogLevel(LogLevel aLevel) {
   switch (aLevel) {
     default:
     case LogLevel::Error:
       return DDLogCategory::MozLogError;
     case LogLevel::Warning:
       return DDLogCategory::MozLogWarning;
     case LogLevel::Info:
       return DDLogCategory::MozLogInfo;
     case LogLevel::Debug:
       return DDLogCategory::MozLogDebug;
     case LogLevel::Verbose:
       return DDLogCategory::MozLogVerbose;
   }
 }

 using LogState = int;
 // Currently disabled, may be enabled on request.
 static constexpr LogState scDisabled = 0;
 // Currently enabled (logging happens), may be shutdown.
 static constexpr LogState scEnabled = 1;
 // Still disabled, but one thread is working on enabling it, nobody else
 // should interfere during this time.
 static constexpr LogState scEnabling = 2;
 // Shutdown, cannot be re-enabled.
 static constexpr LogState scShutdown = 3;
 // Current state.
 // "ReleaseAcquire" because when changing to scEnabled, the just-created
 // sMediaLogs must be accessible to consumers that see scEnabled.
 static Atomic<LogState, ReleaseAcquire> sLogState;

 // If non-null, reason for an abnormal shutdown.
 static const char* sShutdownReason;
};

// Base class to automatically record a class lifetime. Usage:
//   class SomeClass : public DecoderDoctorLifeLogger<SomeClass>
//   {
//     ...
template <typename T>
class DecoderDoctorLifeLogger {
protected:
 DecoderDoctorLifeLogger() {
   DecoderDoctorLogger::LogConstruction(NonDereferenceable<const T>(this));
 }
 ~DecoderDoctorLifeLogger() {
   DecoderDoctorLogger::LogDestruction(NonDereferenceable<const T>(this));
 }
};

// Macros to help lazily-evaluate arguments, only after we have checked that
// logging is enabled.

// Log a single value; see DDLogValue for allowed types.
#define DDLOG(_category, _label, _arg)                                   \
 do {                                                                   \
   if (DecoderDoctorLogger::IsDDLoggingEnabled()) {                     \
     DecoderDoctorLogger::EagerLogValue(this, _category, _label, _arg); \
   }                                                                    \
 } while (0)
// Log a single value, with an EXplicit `this`.
#define DDLOGEX(_this, _category, _label, _arg)                           \
 do {                                                                    \
   if (DecoderDoctorLogger::IsDDLoggingEnabled()) {                      \
     DecoderDoctorLogger::EagerLogValue(_this, _category, _label, _arg); \
   }                                                                     \
 } while (0)
// Log a single value, with EXplicit type name and `this`.
#define DDLOGEX2(_typename, _this, _category, _label, _arg)                   \
 do {                                                                        \
   if (DecoderDoctorLogger::IsDDLoggingEnabled()) {                          \
     DecoderDoctorLogger::EagerLogValue(_typename, _this, _category, _label, \
                                        _arg);                               \
   }                                                                         \
 } while (0)

#ifdef DEBUG
// Do a printf format check in DEBUG, with the downside that side-effects (from
// evaluating the arguments) may happen twice! Who would do that anyway?
static void inline MOZ_FORMAT_PRINTF(1, 2) DDLOGPRCheck(const char*, ...) {}
#  define DDLOGPR_CHECK(_fmt, ...) DDLOGPRCheck(_fmt, ##__VA_ARGS__)
#else
#  define DDLOGPR_CHECK(_fmt, ...)
#endif

// Log a printf'd string. Discouraged, please try using DDLOG instead.
#define DDLOGPR(_category, _label, _format, ...)                            \
 do {                                                                      \
   if (DecoderDoctorLogger::IsDDLoggingEnabled()) {                        \
     DDLOGPR_CHECK(_format, ##__VA_ARGS__);                                \
     DecoderDoctorLogger::EagerLogPrintf(this, _category, _label, _format, \
                                         ##__VA_ARGS__);                   \
   }                                                                       \
 } while (0)

// Link a child object.
#define DDLINKCHILD(...)                                          \
 do {                                                            \
   if (DecoderDoctorLogger::IsDDLoggingEnabled()) {              \
     DecoderDoctorLogger::LinkParentAndChild(this, __VA_ARGS__); \
   }                                                             \
 } while (0)

// Unlink a child object.
#define DDUNLINKCHILD(...)                                          \
 do {                                                              \
   if (DecoderDoctorLogger::IsDDLoggingEnabled()) {                \
     DecoderDoctorLogger::UnlinkParentAndChild(this, __VA_ARGS__); \
   }                                                               \
 } while (0)

// Log a printf'd string to DDLogger and/or MOZ_LOG, with an EXplicit `this`.
// Don't even call MOZ_LOG on Android non-release/beta; See Logging.h.
#if !defined(ANDROID) || !defined(RELEASE_OR_BETA)
#  define DDMOZ_LOGEX(_this, _logModule, _logLevel, _format, ...)       \
   do {                                                                \
     if (DecoderDoctorLogger::IsDDLoggingEnabled() ||                  \
         MOZ_LOG_TEST(_logModule, _logLevel)) {                        \
       DDLOGPR_CHECK(_format, ##__VA_ARGS__);                          \
       DecoderDoctorLogger::MozLogPrintf(_this, _logModule, _logLevel, \
                                         _format, ##__VA_ARGS__);      \
     }                                                                 \
   } while (0)
#else
#  define DDMOZ_LOGEX(_this, _logModule, _logLevel, _format, ...)       \
   do {                                                                \
     if (DecoderDoctorLogger::IsDDLoggingEnabled()) {                  \
       DDLOGPR_CHECK(_format, ##__VA_ARGS__);                          \
       DecoderDoctorLogger::MozLogPrintf(_this, _logModule, _logLevel, \
                                         _format, ##__VA_ARGS__);      \
     }                                                                 \
   } while (0)
#endif

// Log a printf'd string to DDLogger and/or MOZ_LOG.
#define DDMOZ_LOG(_logModule, _logLevel, _format, ...) \
 DDMOZ_LOGEX(this, _logModule, _logLevel, _format, ##__VA_ARGS__)

}  // namespace mozilla

#endif  // DecoderDoctorLogger_h_