/thirdparty/breakpad/common/mac/GTMLogger.h

http://github.com/tomahawk-player/tomahawk · C++ Header · 458 lines · 98 code · 53 blank · 307 comment · 1 complexity · 7ce9937b4e95a576537fb732b78372d3 MD5 · raw file

  1. //
  2. // GTMLogger.h
  3. //
  4. // Copyright 2007-2008 Google Inc.
  5. //
  6. // Licensed under the Apache License, Version 2.0 (the "License"); you may not
  7. // use this file except in compliance with the License. You may obtain a copy
  8. // of the License at
  9. //
  10. // http://www.apache.org/licenses/LICENSE-2.0
  11. //
  12. // Unless required by applicable law or agreed to in writing, software
  13. // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  14. // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  15. // License for the specific language governing permissions and limitations under
  16. // the License.
  17. //
  18. // Key Abstractions
  19. // ----------------
  20. //
  21. // This file declares multiple classes and protocols that are used by the
  22. // GTMLogger logging system. The 4 main abstractions used in this file are the
  23. // following:
  24. //
  25. // * logger (GTMLogger) - The main logging class that users interact with. It
  26. // has methods for logging at different levels and uses a log writer, a log
  27. // formatter, and a log filter to get the job done.
  28. //
  29. // * log writer (GTMLogWriter) - Writes a given string to some log file, where
  30. // a "log file" can be a physical file on disk, a POST over HTTP to some URL,
  31. // or even some in-memory structure (e.g., a ring buffer).
  32. //
  33. // * log formatter (GTMLogFormatter) - Given a format string and arguments as
  34. // a va_list, returns a single formatted NSString. A "formatted string" could
  35. // be a string with the date prepended, a string with values in a CSV format,
  36. // or even a string of XML.
  37. //
  38. // * log filter (GTMLogFilter) - Given a formatted log message as an NSString
  39. // and the level at which the message is to be logged, this class will decide
  40. // whether the given message should be logged or not. This is a flexible way
  41. // to filter out messages logged at a certain level, messages that contain
  42. // certain text, or filter nothing out at all. This gives the caller the
  43. // flexibility to dynamically enable debug logging in Release builds.
  44. //
  45. // This file also declares some classes to handle the common log writer, log
  46. // formatter, and log filter cases. Callers can also create their own writers,
  47. // formatters, and filters and they can even build them on top of the ones
  48. // declared here. Keep in mind that your custom writer/formatter/filter may be
  49. // called from multiple threads, so it must be thread-safe.
  50. #import <Foundation/Foundation.h>
  51. #import "GTMDefines.h"
  52. // Predeclaration of used protocols that are declared later in this file.
  53. @protocol GTMLogWriter, GTMLogFormatter, GTMLogFilter;
  54. #if MAC_OS_X_VERSION_MIN_REQUIRED >= MAC_OS_X_VERSION_10_5
  55. #define CHECK_FORMAT_NSSTRING(a, b) __attribute__((format(__NSString__, a, b)))
  56. #else
  57. #define CHECK_FORMAT_NSSTRING(a, b)
  58. #endif
  59. // GTMLogger
  60. //
  61. // GTMLogger is the primary user-facing class for an object-oriented logging
  62. // system. It is built on the concept of log formatters (GTMLogFormatter), log
  63. // writers (GTMLogWriter), and log filters (GTMLogFilter). When a message is
  64. // sent to a GTMLogger to log a message, the message is formatted using the log
  65. // formatter, then the log filter is consulted to see if the message should be
  66. // logged, and if so, the message is sent to the log writer to be written out.
  67. //
  68. // GTMLogger is intended to be a flexible and thread-safe logging solution. Its
  69. // flexibility comes from the fact that GTMLogger instances can be customized
  70. // with user defined formatters, filters, and writers. And these writers,
  71. // filters, and formatters can be combined, stacked, and customized in arbitrary
  72. // ways to suit the needs at hand. For example, multiple writers can be used at
  73. // the same time, and a GTMLogger instance can even be used as another
  74. // GTMLogger's writer. This allows for arbitrarily deep logging trees.
  75. //
  76. // A standard GTMLogger uses a writer that sends messages to standard out, a
  77. // formatter that smacks a timestamp and a few other bits of interesting
  78. // information on the message, and a filter that filters out debug messages from
  79. // release builds. Using the standard log settings, a log message will look like
  80. // the following:
  81. //
  82. // 2007-12-30 10:29:24.177 myapp[4588/0xa07d0f60] [lvl=1] foo=<Foo: 0x123>
  83. //
  84. // The output contains the date and time of the log message, the name of the
  85. // process followed by its process ID/thread ID, the log level at which the
  86. // message was logged (in the previous example the level was 1:
  87. // kGTMLoggerLevelDebug), and finally, the user-specified log message itself (in
  88. // this case, the log message was @"foo=%@", foo).
  89. //
  90. // Multiple instances of GTMLogger can be created, each configured their own
  91. // way. Though GTMLogger is not a singleton (in the GoF sense), it does provide
  92. // access to a shared (i.e., globally accessible) GTMLogger instance. This makes
  93. // it convenient for all code in a process to use the same GTMLogger instance.
  94. // The shared GTMLogger instance can also be configured in an arbitrary, and
  95. // these configuration changes will affect all code that logs through the shared
  96. // instance.
  97. //
  98. // Log Levels
  99. // ----------
  100. // GTMLogger has 3 different log levels: Debug, Info, and Error. GTMLogger
  101. // doesn't take any special action based on the log level; it simply forwards
  102. // this information on to formatters, filters, and writers, each of which may
  103. // optionally take action based on the level. Since log level filtering is
  104. // performed at runtime, log messages are typically not filtered out at compile
  105. // time. The exception to this rule is that calls to the GTMLoggerDebug() macro
  106. // *ARE* filtered out of non-DEBUG builds. This is to be backwards compatible
  107. // with behavior that many developers are currently used to. Note that this
  108. // means that GTMLoggerDebug(@"hi") will be compiled out of Release builds, but
  109. // [[GTMLogger sharedLogger] logDebug:@"hi"] will NOT be compiled out.
  110. //
  111. // Standard loggers are created with the GTMLogLevelFilter log filter, which
  112. // filters out certain log messages based on log level, and some other settings.
  113. //
  114. // In addition to the -logDebug:, -logInfo:, and -logError: methods defined on
  115. // GTMLogger itself, there are also C macros that make usage of the shared
  116. // GTMLogger instance very convenient. These macros are:
  117. //
  118. // GTMLoggerDebug(...)
  119. // GTMLoggerInfo(...)
  120. // GTMLoggerError(...)
  121. //
  122. // Again, a notable feature of these macros is that GTMLogDebug() calls *will be
  123. // compiled out of non-DEBUG builds*.
  124. //
  125. // Standard Loggers
  126. // ----------------
  127. // GTMLogger has the concept of "standard loggers". A standard logger is simply
  128. // a logger that is pre-configured with some standard/common writer, formatter,
  129. // and filter combination. Standard loggers are created using the creation
  130. // methods beginning with "standard". The alternative to a standard logger is a
  131. // regular logger, which will send messages to stdout, with no special
  132. // formatting, and no filtering.
  133. //
  134. // How do I use GTMLogger?
  135. // ----------------------
  136. // The typical way you will want to use GTMLogger is to simply use the
  137. // GTMLogger*() macros for logging from code. That way we can easily make
  138. // changes to the GTMLogger class and simply update the macros accordingly. Only
  139. // your application startup code (perhaps, somewhere in main()) should use the
  140. // GTMLogger class directly in order to configure the shared logger, which all
  141. // of the code using the macros will be using. Again, this is just the typical
  142. // situation.
  143. //
  144. // To be complete, there are cases where you may want to use GTMLogger directly,
  145. // or even create separate GTMLogger instances for some reason. That's fine,
  146. // too.
  147. //
  148. // Examples
  149. // --------
  150. // The following show some common GTMLogger use cases.
  151. //
  152. // 1. You want to log something as simply as possible. Also, this call will only
  153. // appear in debug builds. In non-DEBUG builds it will be completely removed.
  154. //
  155. // GTMLoggerDebug(@"foo = %@", foo);
  156. //
  157. // 2. The previous example is similar to the following. The major difference is
  158. // that the previous call (example 1) will be compiled out of Release builds
  159. // but this statement will not be compiled out.
  160. //
  161. // [[GTMLogger sharedLogger] logDebug:@"foo = %@", foo];
  162. //
  163. // 3. Send all logging output from the shared logger to a file. We do this by
  164. // creating an NSFileHandle for writing associated with a file, and setting
  165. // that file handle as the logger's writer.
  166. //
  167. // NSFileHandle *f = [NSFileHandle fileHandleForWritingAtPath:@"/tmp/f.log"
  168. // create:YES];
  169. // [[GTMLogger sharedLogger] setWriter:f];
  170. // GTMLoggerError(@"hi"); // This will be sent to /tmp/f.log
  171. //
  172. // 4. Create a new GTMLogger that will log to a file. This example differs from
  173. // the previous one because here we create a new GTMLogger that is different
  174. // from the shared logger.
  175. //
  176. // GTMLogger *logger = [GTMLogger standardLoggerWithPath:@"/tmp/temp.log"];
  177. // [logger logInfo:@"hi temp log file"];
  178. //
  179. // 5. Create a logger that writes to stdout and does NOT do any formatting to
  180. // the log message. This might be useful, for example, when writing a help
  181. // screen for a command-line tool to standard output.
  182. //
  183. // GTMLogger *logger = [GTMLogger logger];
  184. // [logger logInfo:@"%@ version 0.1 usage", progName];
  185. //
  186. // 6. Send log output to stdout AND to a log file. The trick here is that
  187. // NSArrays function as composite log writers, which means when an array is
  188. // set as the log writer, it forwards all logging messages to all of its
  189. // contained GTMLogWriters.
  190. //
  191. // // Create array of GTMLogWriters
  192. // NSArray *writers = [NSArray arrayWithObjects:
  193. // [NSFileHandle fileHandleForWritingAtPath:@"/tmp/f.log" create:YES],
  194. // [NSFileHandle fileHandleWithStandardOutput], nil];
  195. //
  196. // GTMLogger *logger = [GTMLogger standardLogger];
  197. // [logger setWriter:writers];
  198. // [logger logInfo:@"hi"]; // Output goes to stdout and /tmp/f.log
  199. //
  200. // For futher details on log writers, formatters, and filters, see the
  201. // documentation below.
  202. //
  203. // NOTE: GTMLogger is application level logging. By default it does nothing
  204. // with _GTMDevLog/_GTMDevAssert (see GTMDefines.h). An application can choose
  205. // to bridge _GTMDevLog/_GTMDevAssert to GTMLogger by providing macro
  206. // definitions in its prefix header (see GTMDefines.h for how one would do
  207. // that).
  208. //
  209. @interface GTMLogger : NSObject {
  210. @private
  211. id<GTMLogWriter> writer_;
  212. id<GTMLogFormatter> formatter_;
  213. id<GTMLogFilter> filter_;
  214. }
  215. //
  216. // Accessors for the shared logger instance
  217. //
  218. // Returns a shared/global standard GTMLogger instance. Callers should typically
  219. // use this method to get a GTMLogger instance, unless they explicitly want
  220. // their own instance to configure for their own needs. This is the only method
  221. // that returns a shared instance; all the rest return new GTMLogger instances.
  222. + (id)sharedLogger;
  223. // Sets the shared logger instance to |logger|. Future calls to +sharedLogger
  224. // will return |logger| instead.
  225. + (void)setSharedLogger:(GTMLogger *)logger;
  226. //
  227. // Creation methods
  228. //
  229. // Returns a new autoreleased GTMLogger instance that will log to stdout, using
  230. // the GTMLogStandardFormatter, and the GTMLogLevelFilter filter.
  231. + (id)standardLogger;
  232. // Same as +standardLogger, but logs to stderr.
  233. + (id)standardLoggerWithStderr;
  234. // Returns a new standard GTMLogger instance with a log writer that will
  235. // write to the file at |path|, and will use the GTMLogStandardFormatter and
  236. // GTMLogLevelFilter classes. If |path| does not exist, it will be created.
  237. + (id)standardLoggerWithPath:(NSString *)path;
  238. // Returns an autoreleased GTMLogger instance that will use the specified
  239. // |writer|, |formatter|, and |filter|.
  240. + (id)loggerWithWriter:(id<GTMLogWriter>)writer
  241. formatter:(id<GTMLogFormatter>)formatter
  242. filter:(id<GTMLogFilter>)filter;
  243. // Returns an autoreleased GTMLogger instance that logs to stdout, with the
  244. // basic formatter, and no filter. The returned logger differs from the logger
  245. // returned by +standardLogger because this one does not do any filtering and
  246. // does not do any special log formatting; this is the difference between a
  247. // "regular" logger and a "standard" logger.
  248. + (id)logger;
  249. // Designated initializer. This method returns a GTMLogger initialized with the
  250. // specified |writer|, |formatter|, and |filter|. See the setter methods below
  251. // for what values will be used if nil is passed for a parameter.
  252. - (id)initWithWriter:(id<GTMLogWriter>)writer
  253. formatter:(id<GTMLogFormatter>)formatter
  254. filter:(id<GTMLogFilter>)filter;
  255. //
  256. // Logging methods
  257. //
  258. // Logs a message at the debug level (kGTMLoggerLevelDebug).
  259. - (void)logDebug:(NSString *)fmt, ... CHECK_FORMAT_NSSTRING(1, 2);
  260. // Logs a message at the info level (kGTMLoggerLevelInfo).
  261. - (void)logInfo:(NSString *)fmt, ... CHECK_FORMAT_NSSTRING(1, 2);
  262. // Logs a message at the error level (kGTMLoggerLevelError).
  263. - (void)logError:(NSString *)fmt, ... CHECK_FORMAT_NSSTRING(1, 2);
  264. // Logs a message at the assert level (kGTMLoggerLevelAssert).
  265. - (void)logAssert:(NSString *)fmt, ... CHECK_FORMAT_NSSTRING(1, 2);
  266. //
  267. // Accessors
  268. //
  269. // Accessor methods for the log writer. If the log writer is set to nil,
  270. // [NSFileHandle fileHandleWithStandardOutput] is used.
  271. - (id<GTMLogWriter>)writer;
  272. - (void)setWriter:(id<GTMLogWriter>)writer;
  273. // Accessor methods for the log formatter. If the log formatter is set to nil,
  274. // GTMLogBasicFormatter is used. This formatter will format log messages in a
  275. // plain printf style.
  276. - (id<GTMLogFormatter>)formatter;
  277. - (void)setFormatter:(id<GTMLogFormatter>)formatter;
  278. // Accessor methods for the log filter. If the log filter is set to nil,
  279. // GTMLogNoFilter is used, which allows all log messages through.
  280. - (id<GTMLogFilter>)filter;
  281. - (void)setFilter:(id<GTMLogFilter>)filter;
  282. @end // GTMLogger
  283. // Helper functions that are used by the convenience GTMLogger*() macros that
  284. // enable the logging of function names.
  285. @interface GTMLogger (GTMLoggerMacroHelpers)
  286. - (void)logFuncDebug:(const char *)func msg:(NSString *)fmt, ...
  287. CHECK_FORMAT_NSSTRING(2, 3);
  288. - (void)logFuncInfo:(const char *)func msg:(NSString *)fmt, ...
  289. CHECK_FORMAT_NSSTRING(2, 3);
  290. - (void)logFuncError:(const char *)func msg:(NSString *)fmt, ...
  291. CHECK_FORMAT_NSSTRING(2, 3);
  292. - (void)logFuncAssert:(const char *)func msg:(NSString *)fmt, ...
  293. CHECK_FORMAT_NSSTRING(2, 3);
  294. @end // GTMLoggerMacroHelpers
  295. // Convenience macros that log to the shared GTMLogger instance. These macros
  296. // are how users should typically log to GTMLogger. Notice that GTMLoggerDebug()
  297. // calls will be compiled out of non-Debug builds.
  298. #define GTMLoggerDebug(...) \
  299. [[GTMLogger sharedLogger] logFuncDebug:__func__ msg:__VA_ARGS__]
  300. #define GTMLoggerInfo(...) \
  301. [[GTMLogger sharedLogger] logFuncInfo:__func__ msg:__VA_ARGS__]
  302. #define GTMLoggerError(...) \
  303. [[GTMLogger sharedLogger] logFuncError:__func__ msg:__VA_ARGS__]
  304. #define GTMLoggerAssert(...) \
  305. [[GTMLogger sharedLogger] logFuncAssert:__func__ msg:__VA_ARGS__]
  306. // If we're not in a debug build, remove the GTMLoggerDebug statements. This
  307. // makes calls to GTMLoggerDebug "compile out" of Release builds
  308. #ifndef DEBUG
  309. #undef GTMLoggerDebug
  310. #define GTMLoggerDebug(...) do {} while(0)
  311. #endif
  312. // Log levels.
  313. typedef enum {
  314. kGTMLoggerLevelUnknown,
  315. kGTMLoggerLevelDebug,
  316. kGTMLoggerLevelInfo,
  317. kGTMLoggerLevelError,
  318. kGTMLoggerLevelAssert,
  319. } GTMLoggerLevel;
  320. //
  321. // Log Writers
  322. //
  323. // Protocol to be implemented by a GTMLogWriter instance.
  324. @protocol GTMLogWriter <NSObject>
  325. // Writes the given log message to where the log writer is configured to write.
  326. - (void)logMessage:(NSString *)msg level:(GTMLoggerLevel)level;
  327. @end // GTMLogWriter
  328. // Simple category on NSFileHandle that makes NSFileHandles valid log writers.
  329. // This is convenient because something like, say, +fileHandleWithStandardError
  330. // now becomes a valid log writer. Log messages are written to the file handle
  331. // with a newline appended.
  332. @interface NSFileHandle (GTMFileHandleLogWriter) <GTMLogWriter>
  333. // Opens the file at |path| in append mode, and creates the file with |mode|
  334. // if it didn't previously exist.
  335. + (id)fileHandleForLoggingAtPath:(NSString *)path mode:(mode_t)mode;
  336. @end // NSFileHandle
  337. // This category makes NSArray a GTMLogWriter that can be composed of other
  338. // GTMLogWriters. This is the classic Composite GoF design pattern. When the
  339. // GTMLogWriter -logMessage:level: message is sent to the array, the array
  340. // forwards the message to all of its elements that implement the GTMLogWriter
  341. // protocol.
  342. //
  343. // This is useful in situations where you would like to send log output to
  344. // multiple log writers at the same time. Simply create an NSArray of the log
  345. // writers you wish to use, then set the array as the "writer" for your
  346. // GTMLogger instance.
  347. @interface NSArray (GTMArrayCompositeLogWriter) <GTMLogWriter>
  348. @end // GTMArrayCompositeLogWriter
  349. // This category adapts the GTMLogger interface so that it can be used as a log
  350. // writer; it's an "adapter" in the GoF Adapter pattern sense.
  351. //
  352. // This is useful when you want to configure a logger to log to a specific
  353. // writer with a specific formatter and/or filter. But you want to also compose
  354. // that with a different log writer that may have its own formatter and/or
  355. // filter.
  356. @interface GTMLogger (GTMLoggerLogWriter) <GTMLogWriter>
  357. @end // GTMLoggerLogWriter
  358. //
  359. // Log Formatters
  360. //
  361. // Protocol to be implemented by a GTMLogFormatter instance.
  362. @protocol GTMLogFormatter <NSObject>
  363. // Returns a formatted string using the format specified in |fmt| and the va
  364. // args specified in |args|.
  365. - (NSString *)stringForFunc:(NSString *)func
  366. withFormat:(NSString *)fmt
  367. valist:(va_list)args
  368. level:(GTMLoggerLevel)level;
  369. @end // GTMLogFormatter
  370. // A basic log formatter that formats a string the same way that NSLog (or
  371. // printf) would. It does not do anything fancy, nor does it add any data of its
  372. // own.
  373. @interface GTMLogBasicFormatter : NSObject <GTMLogFormatter>
  374. @end // GTMLogBasicFormatter
  375. // A log formatter that formats the log string like the basic formatter, but
  376. // also prepends a timestamp and some basic process info to the message, as
  377. // shown in the following sample output.
  378. // 2007-12-30 10:29:24.177 myapp[4588/0xa07d0f60] [lvl=1] log mesage here
  379. @interface GTMLogStandardFormatter : GTMLogBasicFormatter {
  380. @private
  381. NSDateFormatter *dateFormatter_; // yyyy-MM-dd HH:mm:ss.SSS
  382. NSString *pname_;
  383. pid_t pid_;
  384. }
  385. @end // GTMLogStandardFormatter
  386. //
  387. // Log Filters
  388. //
  389. // Protocol to be imlemented by a GTMLogFilter instance.
  390. @protocol GTMLogFilter <NSObject>
  391. // Returns YES if |msg| at |level| should be filtered out; NO otherwise.
  392. - (BOOL)filterAllowsMessage:(NSString *)msg level:(GTMLoggerLevel)level;
  393. @end // GTMLogFilter
  394. // A log filter that filters messages at the kGTMLoggerLevelDebug level out of
  395. // non-debug builds. Messages at the kGTMLoggerLevelInfo level are also filtered
  396. // out of non-debug builds unless GTMVerboseLogging is set in the environment or
  397. // the processes's defaults. Messages at the kGTMLoggerLevelError level are
  398. // never filtered.
  399. @interface GTMLogLevelFilter : NSObject <GTMLogFilter>
  400. @end // GTMLogLevelFilter
  401. // A simple log filter that does NOT filter anything out;
  402. // -filterAllowsMessage:level will always return YES. This can be a convenient
  403. // way to enable debug-level logging in release builds (if you so desire).
  404. @interface GTMLogNoFilter : NSObject <GTMLogFilter>
  405. @end // GTMLogNoFilter