The Tor Browser: toolkit/crashreporter/google-breakpad/src/common/mac/GTMLogger.h@129ffea94266 (annotated)

toolkit/crashreporter/google-breakpad/src/common/mac/GTMLogger.h@129ffea94266 (annotated)

toolkit/crashreporter/google-breakpad/src/common/mac/GTMLogger.h

Sat, 03 Jan 2015 20:18:00 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Sat, 03 Jan 2015 20:18:00 +0100
branch: TOR_BUG_3246
changeset 7: 129ffea94266
permissions: -rw-r--r--

Conditionally enable double key logic according to:
private browsing mode or privacy.thirdparty.isolate preference and
implement in GetCookieStringCommon and FindCookie where it counts...
With some reservations of how to convince FindCookie users to test
condition and pass a nullptr when disabling double key logic.

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

The Tor Browser / annotate

toolkit/crashreporter/google-breakpad/src/common/mac/GTMLogger.h@129ffea94266 (annotated)

toolkit/crashreporter/google-breakpad/src/common/mac/GTMLogger.h