LoggingInterface.h

Enable keyboard shortcuts

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-

 * vim: set ts=8 sts=2 et sw=2 tw=80:

 * 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/. */

// An experimental logging interface for connecting the JS Engine to some

// (*cough*Gecko*cough*) consumer.

#ifndef _js_experimental_LoggingInterface_h_

#define _js_experimental_LoggingInterface_h_

#include "mozilla/LoggingCore.h"

#include "jstypes.h"

#include "js/GCAPI.h"

struct JSContext;

namespace JS {

// An Opaque pointer to a LoggerType. It must be possible for this logger type

// to conform to the interface below, using the LogLevel type exported in

// mozglue LoggingCore.h

//

// There are some requirements that we cannot express through the type-system:

//

// - A Logger must outlive any caller. This is an obvious statement, but in the

//   context of the JS engine means that a logger must live until after the JS

//   engine is shutdown.

// - A logger cannot move. The logging interfaces assumes 1) That an

//   OpaqueLogger will remain a valid handle to a logger for the entire duration

//   of an initialize JS library, and 2) We are able to cache a reference to the

//   log level of a particular logger (see getLevelRef below).

using OpaqueLogger = void*;

// [SMDOC] Logging Interface

//

// The logging interface contains a set of function pointers which explain how

// to talk to an embedder provided logging system.

//

// The design of the JS Consumer of this relies heavily on these to be freely

// copyable.

struct LoggingInterface {

  // Acquire a new logger for a given name.

//

  // This interface has no way of indicating backwards that a logger is no

  // longer needed, and as such this pointer needs to be kept alive by the

  // embedding for the lifetime of the JS engine.

  OpaqueLogger (*getLoggerByName)(const char* loggerName) = nullptr;

  // Print a message to a particular logger with a particular level and

  // format.

  void (*logPrintVA)(const OpaqueLogger aModule, mozilla::LogLevel aLevel,

                     const char* aFmt, va_list ap)

      MOZ_FORMAT_PRINTF(3, 0) = nullptr;

  // Return a reference to the provided OpaqueLogger's level ref; Implementation

  // wise this can be a small violation of encapsulation but is intended to help

  // ensure that we can build lightweight logging without egregious costs to

  // simply check even if a mesage will the writen

  mozilla::AtomicLogLevel& (*getLevelRef)(OpaqueLogger) = nullptr;

  // Wrapper function for calling va-version

  void logPrint(const OpaqueLogger aModule, mozilla::LogLevel aLevel,

                const char* aFmt, ...) MOZ_FORMAT_PRINTF(4, 5) {

    JS::AutoSuppressGCAnalysis suppress;

    va_list ap;

    va_start(ap, aFmt);

    this->logPrintVA(aModule, aLevel, aFmt, ap);

    va_end(ap);

  // Used to ensure that before we use an interface, it's successfully been

  // completely filled in.

  bool isComplete() const {

    return getLoggerByName && logPrintVA && getLevelRef;

};

// Install the logging interface. This will also install the interface into

// any JS loggers

extern JS_PUBLIC_API bool SetLoggingInterface(LoggingInterface& iface);

}  // namespace JS

#endif /* _js_experimental_LoggingInterface_h_ */