mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-13 21:35:39 +00:00
441 lines
15 KiB
Plaintext
441 lines
15 KiB
Plaintext
/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
|
|
*
|
|
* The contents of this file are subject to the Netscape Public
|
|
* License Version 1.1 (the "License"); you may not use this file
|
|
* except in compliance with the License. You may obtain a copy of
|
|
* the License at http://www.mozilla.org/NPL/
|
|
*
|
|
* Software distributed under the License is distributed on an "AS
|
|
* IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
|
|
* implied. See the License for the specific language governing
|
|
* rights and limitations under the License.
|
|
*
|
|
* The Original Code is mozilla.org code.
|
|
*
|
|
* The Initial Developer of the Original Code is Netscape
|
|
* Communications Corporation. Portions created by Netscape are
|
|
* Copyright (C) 1998 Netscape Communications Corporation. All
|
|
* Rights Reserved.
|
|
*
|
|
* Contributor(s):
|
|
*/
|
|
|
|
/**
|
|
* LOGGING SERVICE
|
|
*
|
|
* We all know and love PR_LOG, but let's face it, it has some deficiencies:
|
|
* - can't direct output for different logs to different places,
|
|
* - isn't scriptable,
|
|
* - can't control printing format, including indentation,
|
|
* - no facilities for interval timing.
|
|
* We've solved these problems with NS_LOG, the new modern equivalent. Here's
|
|
* how you use it:
|
|
*
|
|
* // First declare a new log:
|
|
* NS_DECL_LOG(Foo);
|
|
*
|
|
* void main() {
|
|
* nsresult rv;
|
|
*
|
|
* // Initialize the log somewhere in your startup code:
|
|
* NS_INIT_LOG(Foo, &rv);
|
|
*
|
|
* // Then use it like this:
|
|
* NS_LOG(Foo, OUT, ("hello world"));
|
|
* }
|
|
*
|
|
* The above log statement will print something like this:
|
|
*
|
|
* a33e50 Foo hello world
|
|
*
|
|
* The hex number at the beginning of the line indicates the ID of the thread
|
|
* executing the NS_LOG statement. The name of the log appears next. And if
|
|
* the constant ERROR, WARN, or DBG had appeared instead of OUT in the NS_LOG
|
|
* statement, the character 'E', 'W' or 'D' would have appeared before the
|
|
* message to indicate the type of log statement. The level displayed can
|
|
* be controlled by calling SetLevel on the log.
|
|
*
|
|
* // You can also cause it to indent its output to help you log recursive execution:
|
|
* int fact(int n) {
|
|
* NS_LOG_WITH_INDENT(Foo, "fact");
|
|
* NS_LOG(Main, ERROR, ("calling fact of %d\n", n));
|
|
* if (n == 0) return 1;
|
|
* int result = n * fact(n - 1);
|
|
* NS_LOG(Foo, DBG, ("fact of %d is %d\n", n, result));
|
|
* return result;
|
|
* }
|
|
*
|
|
* Calling fact(3) will produce a log that looks like this:
|
|
*
|
|
* a33e50 Foo D | calling fact of 3
|
|
* a33e50 Foo D | | calling fact of 2
|
|
* a33e50 Foo D | | | calling fact of 1
|
|
* a33e50 Foo D | | | | calling fact of 0
|
|
* a33e50 Foo D | | | fact of 1 is 1
|
|
* a33e50 Foo D | | fact of 2 is 2
|
|
* a33e50 Foo D | fact of 3 is 6
|
|
*
|
|
* You can compute elapsed time for a series of runs, and then ask the log for
|
|
* statistical information on them:
|
|
*
|
|
* void TestTiming() {
|
|
* for (int i = 0; i < 100; i++) {
|
|
* NS_LOG_BEGIN_TIMING(Foo);
|
|
* CallTestToTime();
|
|
* PRIntervalTime elapsed;
|
|
* NS_LOG_END_TIMING(Foo, &elapsed);
|
|
* NS_LOG(Foo, OUT, ("time for this run: %f\n", elapsed));
|
|
* }
|
|
* #ifdef NS_ENABLE_LOGGING
|
|
* PRUint32 samples;
|
|
* double mean, stdDev;
|
|
* Foo->GetTimingStats(&samples, &mean, &stdDev);
|
|
* printf("samples: %d, mean: %f, standard deviation: %f\n",
|
|
* samples, mean, stdDev);
|
|
* #endif
|
|
* }
|
|
*
|
|
* You can control where the output of the log goes by setting its
|
|
* log event sink to an appropriate nsILogEventSink. By default the
|
|
* standard log event sink does the following:
|
|
* - outputs to stderr
|
|
* - outputs to the platform's debug output for errors
|
|
* New log event sinks can be instantiated via the component manager:
|
|
*
|
|
* nsComponentManager::CreateInstance(kStandardLogEventSinkCID,
|
|
* nsnull, NS_GET_IID(nsIStandardLogEventSink),
|
|
* &logEventSink);
|
|
* logEventSink->Init(stdout, // stdout instead of stderr
|
|
* nsILog::LEVEL_WARN); // level to log to debug output
|
|
* Foo->SetLogEventSink(logEventSink);
|
|
*
|
|
* or the application can implement its own nsILogEventSink.
|
|
*/
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#include "nsISupports.idl"
|
|
|
|
%{C++
|
|
|
|
#include "prlog.h" // include prlog.h because we're going to override it's ancient macros
|
|
#include "prprf.h"
|
|
#include "prinrval.h"
|
|
#include "nsDebug.h"
|
|
#include "nsIServiceManager.h"
|
|
#include <stdio.h>
|
|
|
|
#if (defined(DEBUG) || defined(NS_DEBUG) || defined(FORCE_PR_LOG)) && !defined(WIN16)
|
|
// enable logging by default
|
|
#define NS_ENABLE_LOGGING
|
|
#endif
|
|
|
|
#ifdef NS_DISABLE_LOGGING
|
|
// override, if you want DEBUG, but *not* logging (for some reason)
|
|
#undef NS_ENABLE_LOGGING
|
|
#endif
|
|
|
|
#ifdef NS_ENABLE_LOGGING
|
|
|
|
class nsLogEvent;
|
|
|
|
%}
|
|
|
|
[ref] native nsLogEvent(nsLogEvent);
|
|
|
|
typedef unsigned long PRIntervalTime;
|
|
|
|
interface nsILog;
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
[scriptable, uuid(28efb190-b114-11d3-93b6-00104ba0fd40)]
|
|
interface nsILogEventSink : nsISupports
|
|
{
|
|
[noscript] void printEvent(in nsLogEvent event);
|
|
void flush();
|
|
readonly attribute string destinationName;
|
|
};
|
|
|
|
[ptr] native FILE(FILE);
|
|
|
|
interface nsIStandardLogEventSink : nsILogEventSink
|
|
{
|
|
/**
|
|
* @param filePath - a native path to a log file,
|
|
* or if "1", stdout,
|
|
* or if "2", stderr.
|
|
*/
|
|
void init(in string filePath,
|
|
in unsigned long levelForDebugOutput);
|
|
[noscript] void initFromFILE(in string name,
|
|
in FILE filePtr,
|
|
in unsigned long levelForDebugOutput);
|
|
};
|
|
|
|
%{C++
|
|
#define NS_STANDARDLOGEVENTSINK_CID \
|
|
{ /* 0ebdebe0-b14a-11d3-93b6-00104ba0fd40 */ \
|
|
0x0ebdebe0, \
|
|
0xb14a, \
|
|
0x11d3, \
|
|
{0x93, 0xb6, 0x00, 0x10, 0x4b, 0xa0, 0xfd, 0x40} \
|
|
}
|
|
|
|
#define NS_STANDARDLOGEVENTSINK_PROGID "component://netscape/standard-log-event-sink"
|
|
#define NS_STANDARDLOGEVENTSINK_CLASSNAME "Standard Log Event Sink"
|
|
%}
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
[scriptable, uuid(399d2370-b114-11d3-93b6-00104ba0fd40)]
|
|
interface nsILoggingService : nsISupports
|
|
{
|
|
nsILog getLog(in string name);
|
|
attribute unsigned long defaultControlFlags;
|
|
attribute nsILogEventSink defaultLogEventSink;
|
|
void describeLogs(in nsILog output);
|
|
void describeTimings(in nsILog output);
|
|
};
|
|
|
|
%{C++
|
|
#define NS_LOGGINGSERVICE_CID \
|
|
{ /* 4f290320-b11c-11d3-93b6-00104ba0fd40 */ \
|
|
0x4f290320, \
|
|
0xb11c, \
|
|
0x11d3, \
|
|
{0x93, 0xb6, 0x00, 0x10, 0x4b, 0xa0, 0xfd, 0x40} \
|
|
}
|
|
|
|
#define NS_LOGGINGSERVICE_PROGID "component://netscape/logging-service"
|
|
#define NS_LOGGINGSERVICE_CLASSNAME "Logging Service"
|
|
%}
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
[scriptable, uuid(3cddf0a0-b114-11d3-93b6-00104ba0fd40)]
|
|
interface nsILog : nsISupports
|
|
{
|
|
readonly attribute string name;
|
|
|
|
const unsigned long LEVEL_NEVER = 0;
|
|
const unsigned long LEVEL_ERROR = 1;
|
|
const unsigned long LEVEL_WARN = 2;
|
|
const unsigned long LEVEL_STDOUT = 3;
|
|
const unsigned long LEVEL_DBG = 4;
|
|
|
|
attribute unsigned long level;
|
|
|
|
// Backward compatibility with PR_LOG -- don't use explicitly!
|
|
const unsigned long LEVEL_PR_LOG_NONE = LEVEL_NEVER;
|
|
const unsigned long LEVEL_PR_LOG_ERROR = LEVEL_ERROR;
|
|
const unsigned long LEVEL_PR_LOG_WARNING = LEVEL_WARN;
|
|
const unsigned long LEVEL_PR_LOG_ALWAYS = LEVEL_STDOUT;
|
|
const unsigned long LEVEL_PR_LOG_DEBUG = LEVEL_DBG;
|
|
|
|
////////////////////////////////////////////////////////////////////////////
|
|
// Printing Routines
|
|
|
|
boolean enabled(in unsigned long level);
|
|
void print(in unsigned long level, in wstring message);
|
|
void flush();
|
|
|
|
[noscript] void printEvent(in nsLogEvent event);
|
|
|
|
void increaseIndent();
|
|
void decreaseIndent();
|
|
readonly attribute unsigned long indentLevel;
|
|
|
|
void describe(in nsILog outLog);
|
|
|
|
////////////////////////////////////////////////////////////////////////////
|
|
// Timing Routines
|
|
|
|
void beginTiming();
|
|
PRIntervalTime endTiming();
|
|
void getTimingStats(out unsigned long sampleSize,
|
|
out double meanTime,
|
|
out double stdDevTime);
|
|
void describeTiming(in nsILog outLog, in string msg);
|
|
void resetTiming();
|
|
|
|
////////////////////////////////////////////////////////////////////////////
|
|
// Control Routines
|
|
|
|
const unsigned long PRINT_THREAD_ID = 1 << 0;
|
|
const unsigned long PRINT_LOG_NAME = 1 << 1;
|
|
const unsigned long PRINT_LEVEL = 1 << 2;
|
|
const unsigned long TIMING_PER_THREAD = 1 << 3;
|
|
|
|
attribute unsigned long controlFlags;
|
|
|
|
attribute nsILogEventSink logEventSink;
|
|
|
|
////////////////////////////////////////////////////////////////////////////
|
|
|
|
// What's this? Why is this sort of thing in an interface definition?
|
|
// The reason is that testing whether a log is enabled from C++
|
|
// programs must be efficient so as not to impact the execution
|
|
// of time-critical operations, yet still allow for logging them
|
|
// in order to detect problems. (We're basically forcing every
|
|
// implementation to implement this part.)
|
|
%{C++
|
|
public:
|
|
PRBool Test(PRUint32 level) { return mEnabledLevel >= level; }
|
|
protected:
|
|
PRUint32 mEnabledLevel;
|
|
%}
|
|
};
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
%{C++
|
|
|
|
/**
|
|
* nsLogEvent: This little closure class is used to capture the log
|
|
* level so that the NS_LOG macro is more manageable.
|
|
*/
|
|
class NS_COM nsLogEvent
|
|
{
|
|
public:
|
|
nsLogEvent(nsILog* log, PRUint32 level)
|
|
: mLog(log), mLevel(level), mMessage(nsnull) {
|
|
}
|
|
~nsLogEvent() {
|
|
if (mMessage) PR_smprintf_free(mMessage);
|
|
}
|
|
|
|
nsresult Printf(const char* format, ...);
|
|
nsresult Vprintf(const char* format, va_list args);
|
|
|
|
nsILog* GetLog() { return mLog; }
|
|
PRUint32 GetLevel() { return mLevel; }
|
|
const char* GetMsg() { return mMessage; }
|
|
|
|
protected:
|
|
nsILog* mLog;
|
|
PRUint32 mLevel;
|
|
char* mMessage;
|
|
};
|
|
|
|
/**
|
|
* nsLogIndent: This class allows indentation to occur in a block scope. The
|
|
* automatic destructor takes care of resetting the indentation. Use the
|
|
* NS_LOG_WITH_INDENT macro.
|
|
*/
|
|
class NS_COM nsLogIndent
|
|
{
|
|
public:
|
|
nsLogIndent(nsILog* log, const char* msg) : mLog(log), mMsg(msg) {
|
|
nsLogEvent(mLog, nsILog::LEVEL_STDOUT).Printf("[ Begin %s", mMsg);
|
|
mLog->IncreaseIndent();
|
|
}
|
|
~nsLogIndent() {
|
|
mLog->DecreaseIndent();
|
|
nsLogEvent(mLog, nsILog::LEVEL_STDOUT).Printf("] End %s", mMsg);
|
|
}
|
|
protected:
|
|
nsILog* mLog;
|
|
const char* mMsg;
|
|
};
|
|
|
|
/**
|
|
* nsLogTiming: This class allows timing to occur in a block scope. The
|
|
* automatic destructor takes care of stopping the timing. Use the
|
|
* NS_LOG_WITH_TIMING macro.
|
|
*/
|
|
class NS_COM nsLogTiming
|
|
{
|
|
public:
|
|
nsLogTiming(nsILog* log) : mLog(log) {
|
|
mLog->BeginTiming();
|
|
}
|
|
~nsLogTiming() {
|
|
PRIntervalTime elapsed;
|
|
mLog->EndTiming(&elapsed);
|
|
}
|
|
protected:
|
|
nsILog* mLog;
|
|
};
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
#define NS_DECL_LOG(_log) \
|
|
nsILog* _log
|
|
|
|
#define NS_INIT_LOG(_log) \
|
|
PR_BEGIN_MACRO \
|
|
if (_log == nsnull) { \
|
|
nsresult _rv; \
|
|
static NS_DEFINE_CID(kLoggingServiceCID, NS_LOGGINGSERVICE_CID); \
|
|
NS_WITH_SERVICE(nsILoggingService, _serv, kLoggingServiceCID, &_rv); \
|
|
if (NS_SUCCEEDED(_rv)) { \
|
|
_rv = _serv->GetLog(#_log, &_log); \
|
|
PR_ASSERT(NS_SUCCEEDED(_rv)); \
|
|
} \
|
|
} \
|
|
PR_END_MACRO
|
|
|
|
#define NS_LOG_TEST(_log, _level) \
|
|
((_log)->Test(nsILog::LEVEL_##_level))
|
|
|
|
#define NS_LOG(_log, _level, _printfArgs) \
|
|
PR_BEGIN_MACRO \
|
|
if (NS_LOG_TEST(_log, _level)) { \
|
|
nsLogEvent(_log, nsILog::LEVEL_##_level) \
|
|
.Printf _printfArgs; \
|
|
} \
|
|
PR_END_MACRO
|
|
|
|
#define NS_DEFINE_LOG(_log, _level) \
|
|
(!NS_LOG_TEST(_log, _level)) \
|
|
? NS_OK \
|
|
: nsLogEvent(_log, nsILog::LEVEL_##_level).Printf
|
|
|
|
#define NS_LOG_FLUSH(_log) ((_log)->Flush())
|
|
|
|
#define NS_LOG_WITH_INDENT(_log, _msg) nsLogIndent _indent_##_log(_log, _msg)
|
|
#define NS_LOG_BEGIN_INDENT(_log) ((_log)->IncreaseIndent())
|
|
#define NS_LOG_END_INDENT(_log) ((_log)->DecreaseIndent())
|
|
|
|
#define NS_LOG_WITH_TIMING(_log) nsLogTiming _timing_##_log(_log)
|
|
#define NS_LOG_BEGIN_TIMING(_log) ((_log)->BeginTiming())
|
|
#define NS_LOG_END_TIMING(_log, _elapsed) ((_log)->EndTiming(_elapsed))
|
|
#define NS_LOG_DESCRIBE_TIMING(_log,_msg) ((_log)->DescribeTiming(_msg))
|
|
#define NS_LOG_RESET_TIMING(_log) ((_log)->ResetTiming())
|
|
|
|
#else // !NS_ENABLE_LOGGING
|
|
|
|
#define NS_DECL_LOG(_log) void _not_used() // something that can be used with extern
|
|
#define NS_INIT_LOG(_log) ((void)0)
|
|
#define NS_LOG_TEST(_module, _level) 0
|
|
#define NS_LOG(_module, _level, _args) ((void)0)
|
|
#define NS_DEFINE_LOG(_log, _level) NS_OK
|
|
#define NS_LOG_FLUSH(_log) NS_OK
|
|
#define NS_LOG_WITH_INDENT(_log, _msg) ((void)0)
|
|
#define NS_LOG_BEGIN_INDENT(_log) ((void)0)
|
|
#define NS_LOG_END_INDENT(_log) ((void)0)
|
|
#define NS_LOG_WITH_TIMING(_log) ((void)0)
|
|
#define NS_LOG_BEGIN_TIMING(_log) ((void)0)
|
|
#define NS_LOG_END_TIMING(_log, _elapsed) (*(_elapsed) = 0)
|
|
#define NS_LOG_DESCRIBE_TIMING(_log,_msg) NS_OK
|
|
#define NS_LOG_RESET_TIMING(_log) NS_OK
|
|
|
|
#endif // !NS_ENABLE_LOGGING
|
|
|
|
// Redefine NSPR's logging system:
|
|
#undef PR_LOG_TEST
|
|
#define PR_LOG_TEST NS_LOG_TEST
|
|
#undef PR_LOG
|
|
#define PR_LOG NS_LOG
|
|
#define PRLogModuleInfo #error use_NS_DECL_LOG_instead
|
|
#define PR_NewLogModule #error use_NS_INIT_LOG_instead
|
|
#undef PR_ASSERT
|
|
#define PR_ASSERT(x) NS_ASSERTION(x, #x)
|
|
#define printf use_NS_DECL_LOG_instead
|
|
#define fprintf use_NS_DECL_LOG_instead
|
|
|
|
%}
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|