PageRenderTime 84ms CodeModel.GetById 41ms app.highlight 5ms RepoModel.GetById 35ms app.codeStats 0ms

/gecko_api/include/prlog.h

http://firefox-mac-pdf.googlecode.com/
C++ Header | 264 lines | 65 code | 30 blank | 169 comment | 4 complexity | 8702394f9c1cd696186f637b5de5dcaf MD5 | raw file
  1/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2/* ***** BEGIN LICENSE BLOCK *****
  3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4 *
  5 * The contents of this file are subject to the Mozilla Public License Version
  6 * 1.1 (the "License"); you may not use this file except in compliance with
  7 * the License. You may obtain a copy of the License at
  8 * http://www.mozilla.org/MPL/
  9 *
 10 * Software distributed under the License is distributed on an "AS IS" basis,
 11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 12 * for the specific language governing rights and limitations under the
 13 * License.
 14 *
 15 * The Original Code is the Netscape Portable Runtime (NSPR).
 16 *
 17 * The Initial Developer of the Original Code is
 18 * Netscape Communications Corporation.
 19 * Portions created by the Initial Developer are Copyright (C) 1998-2000
 20 * the Initial Developer. All Rights Reserved.
 21 *
 22 * Contributor(s):
 23 *
 24 * Alternatively, the contents of this file may be used under the terms of
 25 * either the GNU General Public License Version 2 or later (the "GPL"), or
 26 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 27 * in which case the provisions of the GPL or the LGPL are applicable instead
 28 * of those above. If you wish to allow use of your version of this file only
 29 * under the terms of either the GPL or the LGPL, and not to allow others to
 30 * use your version of this file under the terms of the MPL, indicate your
 31 * decision by deleting the provisions above and replace them with the notice
 32 * and other provisions required by the GPL or the LGPL. If you do not delete
 33 * the provisions above, a recipient may use your version of this file under
 34 * the terms of any one of the MPL, the GPL or the LGPL.
 35 *
 36 * ***** END LICENSE BLOCK ***** */
 37
 38#ifndef prlog_h___
 39#define prlog_h___
 40
 41#include "prtypes.h"
 42
 43PR_BEGIN_EXTERN_C
 44
 45/*
 46** prlog.h -- Declare interfaces to NSPR's Logging service
 47**
 48** NSPR provides a logging service that is used by NSPR itself and is
 49** available to client programs.
 50**
 51** To use the service from a client program, you should create a
 52** PRLogModuleInfo structure by calling PR_NewLogModule(). After
 53** creating the LogModule, you can write to the log using the PR_LOG()
 54** macro.
 55**
 56** Initialization of the log service is handled by NSPR initialization.
 57**
 58** At execution time, you must enable the log service. To enable the
 59** log service, set the environment variable: NSPR_LOG_MODULES
 60** variable.
 61**
 62** NSPR_LOG_MODULES variable has the form:
 63**
 64**     <moduleName>:<value>[, <moduleName>:<value>]*
 65**
 66** Where:
 67**  <moduleName> is the name passed to PR_NewLogModule().
 68**  <value> is a numeric constant, e.g. 5. This value is the maximum
 69** value of a log event, enumerated by PRLogModuleLevel, that you want
 70** written to the log.
 71** 
 72** For example: to record all events of greater value than or equal to
 73** PR_LOG_ERROR for a LogModule names "gizmo", say:
 74** 
 75** set NSPR_LOG_MODULES=gizmo:2
 76** 
 77** Note that you must specify the numeric value of PR_LOG_ERROR.
 78** 
 79** Special LogModule names are provided for controlling NSPR's log
 80** service at execution time. These controls should be set in the
 81** NSPR_LOG_MODULES environment variable at execution time to affect
 82** NSPR's log service for your application.
 83** 
 84** The special LogModule "all" enables all LogModules. To enable all
 85** LogModule calls to PR_LOG(), say:
 86** 
 87** set NSPR_LOG_MODULES=all:5
 88** 
 89** The special LogModule name "sync" tells the NSPR log service to do
 90** unbuffered logging.
 91** 
 92** The special LogModule name "bufsize:<size>" tells NSPR to set the
 93** log buffer to <size>.
 94**
 95** The environment variable NSPR_LOG_FILE specifies the log file to use
 96** unless the default of "stderr" is acceptable. For MS Windows
 97** systems, NSPR_LOG_FILE can be set to a special value: "WinDebug"
 98** (case sensitive). This value causes PR_LOG() output to be written
 99** using the Windows API OutputDebugString(). OutputDebugString()
100** writes to the debugger window; some people find this helpful.
101** 
102**
103** To put log messages in your programs, use the PR_LOG macro:
104**
105**     PR_LOG(<module>, <level>, (<printfString>, <args>*));
106**
107** Where <module> is the address of a PRLogModuleInfo structure, and
108** <level> is one of the levels defined by the enumeration:
109** PRLogModuleLevel. <args> is a printf() style of argument list. That
110** is: (fmtstring, ...).
111**
112** Example:
113** 
114** main() {
115**    PRIntn one = 1;
116**    PRLogModuleInfo * myLm = PR_NewLogModule("gizmo");
117**    PR_LOG( myLm, PR_LOG_ALWAYS, ("Log this! %d\n", one)); 
118**    return; 
119** }
120** 
121** Note the use of printf() style arguments as the third agrument(s) to
122** PR_LOG().
123** 
124** After compiling and linking you application, set the environment:
125** 
126** set NSPR_LOG_MODULES=gizmo:5
127** set NSPR_LOG_FILE=logfile.txt
128** 
129** When you execute your application, the string "Log this! 1" will be
130** written to the file "logfile.txt".
131** 
132** Note to NSPR engineers: a number of PRLogModuleInfo structures are
133** defined and initialized in prinit.c. See this module for ideas on
134** what to log where.
135** 
136*/
137
138typedef enum PRLogModuleLevel {
139    PR_LOG_NONE = 0,                /* nothing */
140    PR_LOG_ALWAYS = 1,              /* always printed */
141    PR_LOG_ERROR = 2,               /* error messages */
142    PR_LOG_WARNING = 3,             /* warning messages */
143    PR_LOG_DEBUG = 4,               /* debug messages */
144
145    PR_LOG_NOTICE = PR_LOG_DEBUG,   /* notice messages */
146    PR_LOG_WARN = PR_LOG_WARNING,   /* warning messages */
147    PR_LOG_MIN = PR_LOG_DEBUG,      /* minimal debugging messages */
148    PR_LOG_MAX = PR_LOG_DEBUG       /* maximal debugging messages */
149} PRLogModuleLevel;
150
151/*
152** One of these structures is created for each module that uses logging.
153**    "name" is the name of the module
154**    "level" is the debugging level selected for that module
155*/
156typedef struct PRLogModuleInfo {
157    const char *name;
158    PRLogModuleLevel level;
159    struct PRLogModuleInfo *next;
160} PRLogModuleInfo;
161
162/*
163** Create a new log module.
164*/
165NSPR_API(PRLogModuleInfo*) PR_NewLogModule(const char *name);
166
167/*
168** Set the file to use for logging. Returns PR_FALSE if the file cannot
169** be created
170*/
171NSPR_API(PRBool) PR_SetLogFile(const char *name);
172
173/*
174** Set the size of the logging buffer. If "buffer_size" is zero then the
175** logging becomes "synchronous" (or unbuffered).
176*/
177NSPR_API(void) PR_SetLogBuffering(PRIntn buffer_size);
178
179/*
180** Print a string to the log. "fmt" is a PR_snprintf format type. All
181** messages printed to the log are preceeded by the name of the thread
182** and a time stamp. Also, the routine provides a missing newline if one
183** is not provided.
184*/
185NSPR_API(void) PR_LogPrint(const char *fmt, ...);
186
187/*
188** Flush the log to its file.
189*/
190NSPR_API(void) PR_LogFlush(void);
191
192/*
193** Windoze 16 can't support a large static string space for all of the
194** various debugging strings so logging is not enabled for it.
195*/
196#if (defined(DEBUG) || defined(FORCE_PR_LOG)) && !defined(WIN16)
197#define PR_LOGGING 1
198
199#define PR_LOG_TEST(_module,_level) \
200    ((_module)->level >= (_level))
201
202/*
203** Log something.
204**    "module" is the address of a PRLogModuleInfo structure
205**    "level" is the desired logging level
206**    "args" is a variable length list of arguments to print, in the following
207**       format:  ("printf style format string", ...)
208*/
209#define PR_LOG(_module,_level,_args)     \
210    PR_BEGIN_MACRO             \
211      if (PR_LOG_TEST(_module,_level)) { \
212      PR_LogPrint _args;         \
213      }                     \
214    PR_END_MACRO
215
216#else /* (defined(DEBUG) || defined(FORCE_PR_LOG)) && !defined(WIN16) */
217
218#undef PR_LOGGING
219#define PR_LOG_TEST(module,level) 0
220#define PR_LOG(module,level,args)
221
222#endif /* (defined(DEBUG) || defined(FORCE_PR_LOG)) && !defined(WIN16) */
223
224#ifndef NO_NSPR_10_SUPPORT
225
226#ifdef PR_LOGGING
227#define PR_LOG_BEGIN    PR_LOG
228#define PR_LOG_END      PR_LOG
229#define PR_LOG_DEFINE   PR_NewLogModule
230#else
231#define PR_LOG_BEGIN(module,level,args)
232#define PR_LOG_END(module,level,args)
233#define PR_LOG_DEFINE(_name)    NULL
234#endif /* PR_LOGGING */
235
236#endif /* NO_NSPR_10_SUPPORT */
237
238#if defined(DEBUG) || defined(FORCE_PR_ASSERT)
239
240NSPR_API(void) PR_Assert(const char *s, const char *file, PRIntn ln);
241#define PR_ASSERT(_expr) \
242    ((_expr)?((void)0):PR_Assert(# _expr,__FILE__,__LINE__))
243
244#define PR_NOT_REACHED(_reasonStr) \
245    PR_Assert(_reasonStr,__FILE__,__LINE__)
246
247#else
248
249#define PR_ASSERT(expr) ((void) 0)
250#define PR_NOT_REACHED(reasonStr)
251
252#endif /* defined(DEBUG) || defined(FORCE_PR_ASSERT) */
253
254/*
255** Compile-time assert. "condition" must be a constant expression.
256** The macro can be used only in places where an "extern" declaration is
257** allowed.
258*/
259#define PR_STATIC_ASSERT(condition) \
260    extern void pr_static_assert(int arg[(condition) ? 1 : -1])
261
262PR_END_EXTERN_C
263
264#endif /* prlog_h___ */