diff options
Diffstat (limited to 'toolkit/crashreporter/google-breakpad/src/common/mac/GTMLogger.h')
| -rw-r--r-- | toolkit/crashreporter/google-breakpad/src/common/mac/GTMLogger.h | 504 |
1 files changed, 0 insertions, 504 deletions
diff --git a/toolkit/crashreporter/google-breakpad/src/common/mac/GTMLogger.h b/toolkit/crashreporter/google-breakpad/src/common/mac/GTMLogger.h deleted file mode 100644 index c4fd14029..000000000 --- a/toolkit/crashreporter/google-breakpad/src/common/mac/GTMLogger.h +++ /dev/null @@ -1,504 +0,0 @@ -// -// GTMLogger.h -// -// Copyright 2007-2008 Google Inc. -// -// Licensed under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -// License for the specific language governing permissions and limitations under -// the License. -// - -// Key Abstractions -// ---------------- -// -// This file declares multiple classes and protocols that are used by the -// GTMLogger logging system. The 4 main abstractions used in this file are the -// following: -// -// * logger (GTMLogger) - The main logging class that users interact with. It -// has methods for logging at different levels and uses a log writer, a log -// formatter, and a log filter to get the job done. -// -// * log writer (GTMLogWriter) - Writes a given string to some log file, where -// a "log file" can be a physical file on disk, a POST over HTTP to some URL, -// or even some in-memory structure (e.g., a ring buffer). -// -// * log formatter (GTMLogFormatter) - Given a format string and arguments as -// a va_list, returns a single formatted NSString. A "formatted string" could -// be a string with the date prepended, a string with values in a CSV format, -// or even a string of XML. -// -// * log filter (GTMLogFilter) - Given a formatted log message as an NSString -// and the level at which the message is to be logged, this class will decide -// whether the given message should be logged or not. This is a flexible way -// to filter out messages logged at a certain level, messages that contain -// certain text, or filter nothing out at all. This gives the caller the -// flexibility to dynamically enable debug logging in Release builds. -// -// This file also declares some classes to handle the common log writer, log -// formatter, and log filter cases. Callers can also create their own writers, -// formatters, and filters and they can even build them on top of the ones -// declared here. Keep in mind that your custom writer/formatter/filter may be -// called from multiple threads, so it must be thread-safe. - -#import <Foundation/Foundation.h> -#import "GTMDefines.h" - -// Predeclaration of used protocols that are declared later in this file. -@protocol GTMLogWriter, GTMLogFormatter, GTMLogFilter; - -// GTMLogger -// -// GTMLogger is the primary user-facing class for an object-oriented logging -// system. It is built on the concept of log formatters (GTMLogFormatter), log -// writers (GTMLogWriter), and log filters (GTMLogFilter). When a message is -// sent to a GTMLogger to log a message, the message is formatted using the log -// formatter, then the log filter is consulted to see if the message should be -// logged, and if so, the message is sent to the log writer to be written out. -// -// GTMLogger is intended to be a flexible and thread-safe logging solution. Its -// flexibility comes from the fact that GTMLogger instances can be customized -// with user defined formatters, filters, and writers. And these writers, -// filters, and formatters can be combined, stacked, and customized in arbitrary -// ways to suit the needs at hand. For example, multiple writers can be used at -// the same time, and a GTMLogger instance can even be used as another -// GTMLogger's writer. This allows for arbitrarily deep logging trees. -// -// A standard GTMLogger uses a writer that sends messages to standard out, a -// formatter that smacks a timestamp and a few other bits of interesting -// information on the message, and a filter that filters out debug messages from -// release builds. Using the standard log settings, a log message will look like -// the following: -// -// 2007-12-30 10:29:24.177 myapp[4588/0xa07d0f60] [lvl=1] foo=<Foo: 0x123> -// -// The output contains the date and time of the log message, the name of the -// process followed by its process ID/thread ID, the log level at which the -// message was logged (in the previous example the level was 1: -// kGTMLoggerLevelDebug), and finally, the user-specified log message itself (in -// this case, the log message was @"foo=%@", foo). -// -// Multiple instances of GTMLogger can be created, each configured their own -// way. Though GTMLogger is not a singleton (in the GoF sense), it does provide -// access to a shared (i.e., globally accessible) GTMLogger instance. This makes -// it convenient for all code in a process to use the same GTMLogger instance. -// The shared GTMLogger instance can also be configured in an arbitrary, and -// these configuration changes will affect all code that logs through the shared -// instance. - -// -// Log Levels -// ---------- -// GTMLogger has 3 different log levels: Debug, Info, and Error. GTMLogger -// doesn't take any special action based on the log level; it simply forwards -// this information on to formatters, filters, and writers, each of which may -// optionally take action based on the level. Since log level filtering is -// performed at runtime, log messages are typically not filtered out at compile -// time. The exception to this rule is that calls to the GTMLoggerDebug() macro -// *ARE* filtered out of non-DEBUG builds. This is to be backwards compatible -// with behavior that many developers are currently used to. Note that this -// means that GTMLoggerDebug(@"hi") will be compiled out of Release builds, but -// [[GTMLogger sharedLogger] logDebug:@"hi"] will NOT be compiled out. -// -// Standard loggers are created with the GTMLogLevelFilter log filter, which -// filters out certain log messages based on log level, and some other settings. -// -// In addition to the -logDebug:, -logInfo:, and -logError: methods defined on -// GTMLogger itself, there are also C macros that make usage of the shared -// GTMLogger instance very convenient. These macros are: -// -// GTMLoggerDebug(...) -// GTMLoggerInfo(...) -// GTMLoggerError(...) -// -// Again, a notable feature of these macros is that GTMLogDebug() calls *will be -// compiled out of non-DEBUG builds*. -// -// Standard Loggers -// ---------------- -// GTMLogger has the concept of "standard loggers". A standard logger is simply -// a logger that is pre-configured with some standard/common writer, formatter, -// and filter combination. Standard loggers are created using the creation -// methods beginning with "standard". The alternative to a standard logger is a -// regular logger, which will send messages to stdout, with no special -// formatting, and no filtering. -// -// How do I use GTMLogger? -// ---------------------- -// The typical way you will want to use GTMLogger is to simply use the -// GTMLogger*() macros for logging from code. That way we can easily make -// changes to the GTMLogger class and simply update the macros accordingly. Only -// your application startup code (perhaps, somewhere in main()) should use the -// GTMLogger class directly in order to configure the shared logger, which all -// of the code using the macros will be using. Again, this is just the typical -// situation. -// -// To be complete, there are cases where you may want to use GTMLogger directly, -// or even create separate GTMLogger instances for some reason. That's fine, -// too. -// -// Examples -// -------- -// The following show some common GTMLogger use cases. -// -// 1. You want to log something as simply as possible. Also, this call will only -// appear in debug builds. In non-DEBUG builds it will be completely removed. -// -// GTMLoggerDebug(@"foo = %@", foo); -// -// 2. The previous example is similar to the following. The major difference is -// that the previous call (example 1) will be compiled out of Release builds -// but this statement will not be compiled out. -// -// [[GTMLogger sharedLogger] logDebug:@"foo = %@", foo]; -// -// 3. Send all logging output from the shared logger to a file. We do this by -// creating an NSFileHandle for writing associated with a file, and setting -// that file handle as the logger's writer. -// -// NSFileHandle *f = [NSFileHandle fileHandleForWritingAtPath:@"/tmp/f.log" -// create:YES]; -// [[GTMLogger sharedLogger] setWriter:f]; -// GTMLoggerError(@"hi"); // This will be sent to /tmp/f.log -// -// 4. Create a new GTMLogger that will log to a file. This example differs from -// the previous one because here we create a new GTMLogger that is different -// from the shared logger. -// -// GTMLogger *logger = [GTMLogger standardLoggerWithPath:@"/tmp/temp.log"]; -// [logger logInfo:@"hi temp log file"]; -// -// 5. Create a logger that writes to stdout and does NOT do any formatting to -// the log message. This might be useful, for example, when writing a help -// screen for a command-line tool to standard output. -// -// GTMLogger *logger = [GTMLogger logger]; -// [logger logInfo:@"%@ version 0.1 usage", progName]; -// -// 6. Send log output to stdout AND to a log file. The trick here is that -// NSArrays function as composite log writers, which means when an array is -// set as the log writer, it forwards all logging messages to all of its -// contained GTMLogWriters. -// -// // Create array of GTMLogWriters -// NSArray *writers = [NSArray arrayWithObjects: -// [NSFileHandle fileHandleForWritingAtPath:@"/tmp/f.log" create:YES], -// [NSFileHandle fileHandleWithStandardOutput], nil]; -// -// GTMLogger *logger = [GTMLogger standardLogger]; -// [logger setWriter:writers]; -// [logger logInfo:@"hi"]; // Output goes to stdout and /tmp/f.log -// -// For futher details on log writers, formatters, and filters, see the -// documentation below. -// -// NOTE: GTMLogger is application level logging. By default it does nothing -// with _GTMDevLog/_GTMDevAssert (see GTMDefines.h). An application can choose -// to bridge _GTMDevLog/_GTMDevAssert to GTMLogger by providing macro -// definitions in its prefix header (see GTMDefines.h for how one would do -// that). -// -@interface GTMLogger : NSObject { - @private - id<GTMLogWriter> writer_; - id<GTMLogFormatter> formatter_; - id<GTMLogFilter> filter_; -} - -// -// Accessors for the shared logger instance -// - -// Returns a shared/global standard GTMLogger instance. Callers should typically -// use this method to get a GTMLogger instance, unless they explicitly want -// their own instance to configure for their own needs. This is the only method -// that returns a shared instance; all the rest return new GTMLogger instances. -+ (id)sharedLogger; - -// Sets the shared logger instance to |logger|. Future calls to +sharedLogger -// will return |logger| instead. -+ (void)setSharedLogger:(GTMLogger *)logger; - -// -// Creation methods -// - -// Returns a new autoreleased GTMLogger instance that will log to stdout, using -// the GTMLogStandardFormatter, and the GTMLogLevelFilter filter. -+ (id)standardLogger; - -// Same as +standardLogger, but logs to stderr. -+ (id)standardLoggerWithStderr; - -// Same as +standardLogger but levels >= kGTMLoggerLevelError are routed to -// stderr, everything else goes to stdout. -+ (id)standardLoggerWithStdoutAndStderr; - -// Returns a new standard GTMLogger instance with a log writer that will -// write to the file at |path|, and will use the GTMLogStandardFormatter and -// GTMLogLevelFilter classes. If |path| does not exist, it will be created. -+ (id)standardLoggerWithPath:(NSString *)path; - -// Returns an autoreleased GTMLogger instance that will use the specified -// |writer|, |formatter|, and |filter|. -+ (id)loggerWithWriter:(id<GTMLogWriter>)writer - formatter:(id<GTMLogFormatter>)formatter - filter:(id<GTMLogFilter>)filter; - -// Returns an autoreleased GTMLogger instance that logs to stdout, with the -// basic formatter, and no filter. The returned logger differs from the logger -// returned by +standardLogger because this one does not do any filtering and -// does not do any special log formatting; this is the difference between a -// "regular" logger and a "standard" logger. -+ (id)logger; - -// Designated initializer. This method returns a GTMLogger initialized with the -// specified |writer|, |formatter|, and |filter|. See the setter methods below -// for what values will be used if nil is passed for a parameter. -- (id)initWithWriter:(id<GTMLogWriter>)writer - formatter:(id<GTMLogFormatter>)formatter - filter:(id<GTMLogFilter>)filter; - -// -// Logging methods -// - -// Logs a message at the debug level (kGTMLoggerLevelDebug). -- (void)logDebug:(NSString *)fmt, ... NS_FORMAT_FUNCTION(1, 2); -// Logs a message at the info level (kGTMLoggerLevelInfo). -- (void)logInfo:(NSString *)fmt, ... NS_FORMAT_FUNCTION(1, 2); -// Logs a message at the error level (kGTMLoggerLevelError). -- (void)logError:(NSString *)fmt, ... NS_FORMAT_FUNCTION(1, 2); -// Logs a message at the assert level (kGTMLoggerLevelAssert). -- (void)logAssert:(NSString *)fmt, ... NS_FORMAT_FUNCTION(1, 2); - - -// -// Accessors -// - -// Accessor methods for the log writer. If the log writer is set to nil, -// [NSFileHandle fileHandleWithStandardOutput] is used. -- (id<GTMLogWriter>)writer; -- (void)setWriter:(id<GTMLogWriter>)writer; - -// Accessor methods for the log formatter. If the log formatter is set to nil, -// GTMLogBasicFormatter is used. This formatter will format log messages in a -// plain printf style. -- (id<GTMLogFormatter>)formatter; -- (void)setFormatter:(id<GTMLogFormatter>)formatter; - -// Accessor methods for the log filter. If the log filter is set to nil, -// GTMLogNoFilter is used, which allows all log messages through. -- (id<GTMLogFilter>)filter; -- (void)setFilter:(id<GTMLogFilter>)filter; - -@end // GTMLogger - - -// Helper functions that are used by the convenience GTMLogger*() macros that -// enable the logging of function names. -@interface GTMLogger (GTMLoggerMacroHelpers) -- (void)logFuncDebug:(const char *)func msg:(NSString *)fmt, ... - NS_FORMAT_FUNCTION(2, 3); -- (void)logFuncInfo:(const char *)func msg:(NSString *)fmt, ... - NS_FORMAT_FUNCTION(2, 3); -- (void)logFuncError:(const char *)func msg:(NSString *)fmt, ... - NS_FORMAT_FUNCTION(2, 3); -- (void)logFuncAssert:(const char *)func msg:(NSString *)fmt, ... - NS_FORMAT_FUNCTION(2, 3); -@end // GTMLoggerMacroHelpers - - -// The convenience macros are only defined if they haven't already been defined. -#ifndef GTMLoggerInfo - -// Convenience macros that log to the shared GTMLogger instance. These macros -// are how users should typically log to GTMLogger. Notice that GTMLoggerDebug() -// calls will be compiled out of non-Debug builds. -#define GTMLoggerDebug(...) \ - [[GTMLogger sharedLogger] logFuncDebug:__func__ msg:__VA_ARGS__] -#define GTMLoggerInfo(...) \ - [[GTMLogger sharedLogger] logFuncInfo:__func__ msg:__VA_ARGS__] -#define GTMLoggerError(...) \ - [[GTMLogger sharedLogger] logFuncError:__func__ msg:__VA_ARGS__] -#define GTMLoggerAssert(...) \ - [[GTMLogger sharedLogger] logFuncAssert:__func__ msg:__VA_ARGS__] - -// If we're not in a debug build, remove the GTMLoggerDebug statements. This -// makes calls to GTMLoggerDebug "compile out" of Release builds -#ifndef DEBUG -#undef GTMLoggerDebug -#define GTMLoggerDebug(...) do {} while(0) -#endif - -#endif // !defined(GTMLoggerInfo) - -// Log levels. -typedef enum { - kGTMLoggerLevelUnknown, - kGTMLoggerLevelDebug, - kGTMLoggerLevelInfo, - kGTMLoggerLevelError, - kGTMLoggerLevelAssert, -} GTMLoggerLevel; - - -// -// Log Writers -// - -// Protocol to be implemented by a GTMLogWriter instance. -@protocol GTMLogWriter <NSObject> -// Writes the given log message to where the log writer is configured to write. -- (void)logMessage:(NSString *)msg level:(GTMLoggerLevel)level; -@end // GTMLogWriter - - -// Simple category on NSFileHandle that makes NSFileHandles valid log writers. -// This is convenient because something like, say, +fileHandleWithStandardError -// now becomes a valid log writer. Log messages are written to the file handle -// with a newline appended. -@interface NSFileHandle (GTMFileHandleLogWriter) <GTMLogWriter> -// Opens the file at |path| in append mode, and creates the file with |mode| -// if it didn't previously exist. -+ (id)fileHandleForLoggingAtPath:(NSString *)path mode:(mode_t)mode; -@end // NSFileHandle - - -// This category makes NSArray a GTMLogWriter that can be composed of other -// GTMLogWriters. This is the classic Composite GoF design pattern. When the -// GTMLogWriter -logMessage:level: message is sent to the array, the array -// forwards the message to all of its elements that implement the GTMLogWriter -// protocol. -// -// This is useful in situations where you would like to send log output to -// multiple log writers at the same time. Simply create an NSArray of the log -// writers you wish to use, then set the array as the "writer" for your -// GTMLogger instance. -@interface NSArray (GTMArrayCompositeLogWriter) <GTMLogWriter> -@end // GTMArrayCompositeLogWriter - - -// This category adapts the GTMLogger interface so that it can be used as a log -// writer; it's an "adapter" in the GoF Adapter pattern sense. -// -// This is useful when you want to configure a logger to log to a specific -// writer with a specific formatter and/or filter. But you want to also compose -// that with a different log writer that may have its own formatter and/or -// filter. -@interface GTMLogger (GTMLoggerLogWriter) <GTMLogWriter> -@end // GTMLoggerLogWriter - - -// -// Log Formatters -// - -// Protocol to be implemented by a GTMLogFormatter instance. -@protocol GTMLogFormatter <NSObject> -// Returns a formatted string using the format specified in |fmt| and the va -// args specified in |args|. -- (NSString *)stringForFunc:(NSString *)func - withFormat:(NSString *)fmt - valist:(va_list)args - level:(GTMLoggerLevel)level NS_FORMAT_FUNCTION(2, 0); -@end // GTMLogFormatter - - -// A basic log formatter that formats a string the same way that NSLog (or -// printf) would. It does not do anything fancy, nor does it add any data of its -// own. -@interface GTMLogBasicFormatter : NSObject <GTMLogFormatter> - -// Helper method for prettying C99 __func__ and GCC __PRETTY_FUNCTION__ -- (NSString *)prettyNameForFunc:(NSString *)func; - -@end // GTMLogBasicFormatter - - -// A log formatter that formats the log string like the basic formatter, but -// also prepends a timestamp and some basic process info to the message, as -// shown in the following sample output. -// 2007-12-30 10:29:24.177 myapp[4588/0xa07d0f60] [lvl=1] log mesage here -@interface GTMLogStandardFormatter : GTMLogBasicFormatter { - @private - NSDateFormatter *dateFormatter_; // yyyy-MM-dd HH:mm:ss.SSS - NSString *pname_; - pid_t pid_; -} -@end // GTMLogStandardFormatter - - -// -// Log Filters -// - -// Protocol to be imlemented by a GTMLogFilter instance. -@protocol GTMLogFilter <NSObject> -// Returns YES if |msg| at |level| should be filtered out; NO otherwise. -- (BOOL)filterAllowsMessage:(NSString *)msg level:(GTMLoggerLevel)level; -@end // GTMLogFilter - - -// A log filter that filters messages at the kGTMLoggerLevelDebug level out of -// non-debug builds. Messages at the kGTMLoggerLevelInfo level are also filtered -// out of non-debug builds unless GTMVerboseLogging is set in the environment or -// the processes's defaults. Messages at the kGTMLoggerLevelError level are -// never filtered. -@interface GTMLogLevelFilter : NSObject <GTMLogFilter> -@end // GTMLogLevelFilter - -// A simple log filter that does NOT filter anything out; -// -filterAllowsMessage:level will always return YES. This can be a convenient -// way to enable debug-level logging in release builds (if you so desire). -@interface GTMLogNoFilter : NSObject <GTMLogFilter> -@end // GTMLogNoFilter - - -// Base class for custom level filters. Not for direct use, use the minimum -// or maximum level subclasses below. -@interface GTMLogAllowedLevelFilter : NSObject <GTMLogFilter> { - @private - NSIndexSet *allowedLevels_; -} -@end - -// A log filter that allows you to set a minimum log level. Messages below this -// level will be filtered. -@interface GTMLogMininumLevelFilter : GTMLogAllowedLevelFilter - -// Designated initializer, logs at levels < |level| will be filtered. -- (id)initWithMinimumLevel:(GTMLoggerLevel)level; - -@end - -// A log filter that allows you to set a maximum log level. Messages whose level -// exceeds this level will be filtered. This is really only useful if you have -// a composite GTMLogger that is sending the other messages elsewhere. -@interface GTMLogMaximumLevelFilter : GTMLogAllowedLevelFilter - -// Designated initializer, logs at levels > |level| will be filtered. -- (id)initWithMaximumLevel:(GTMLoggerLevel)level; - -@end - - -// For subclasses only -@interface GTMLogger (PrivateMethods) - -- (void)logInternalFunc:(const char *)func - format:(NSString *)fmt - valist:(va_list)args - level:(GTMLoggerLevel)level NS_FORMAT_FUNCTION(2, 0); - -@end - |