gecko-dev/xpcom/base/nsILoggingService.idl

441 строка
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
%}
////////////////////////////////////////////////////////////////////////////////