// Software License Agreement (BSD License)
|
//
|
// Copyright (c) 2010-2016, Deusty, LLC
|
// All rights reserved.
|
//
|
// Redistribution and use of this software in source and binary forms,
|
// with or without modification, are permitted provided that the following conditions are met:
|
//
|
// *Redistributions of source code must retain the above copyright notice,
|
// this list of conditions and the following disclaimer.
|
//
|
// *Neither the name of Deusty nor the names of its contributors may be used
|
// to endorse or promote products derived from this software without specific
|
// prior written permission of Deusty, LLC.
|
|
#import <Foundation/Foundation.h>
|
|
// Enable 1.9.x legacy macros if imported directly
|
#ifndef OBSDD_LEGACY_MACROS
|
#define OBSDD_LEGACY_MACROS 1
|
#endif
|
// OBSDD_LEGACY_MACROS is checked in the file itself
|
#import "OBSDDLegacyMacros.h"
|
|
#if OS_OBJECT_USE_OBJC
|
#define DISPATCH_QUEUE_REFERENCE_TYPE strong
|
#else
|
#define DISPATCH_QUEUE_REFERENCE_TYPE assign
|
#endif
|
|
@class OBSDDLogMessage;
|
@class OBSDDLoggerInformation;
|
@protocol OBSDDLogger;
|
@protocol OBSDDLogFormatter;
|
|
/**
|
*Define the standard options.
|
*
|
*We default to only 4 levels because it makes it easier for beginners
|
*to make the transition to a logging framework.
|
*
|
*More advanced users may choose to completely customize the levels (and level names) to suite their needs.
|
*For more information on this see the "Custom Log Levels" page:
|
*Documentation/CustomLogLevels.md
|
*
|
*Advanced users may also notice that we're using a bitmask.
|
*This is to allow for custom fine grained logging:
|
*Documentation/FineGrainedLogging.md
|
*
|
*-- Flags --
|
*
|
*Typically you will use the OBSLOG_LEVELS (see below), but the flags may be used directly in certain situations.
|
*For example, say you have a lot of warning log messages, and you wanted to disable them.
|
*However, you still needed to see your error and info log messages.
|
*You could accomplish that with the following:
|
*
|
*static const OBSDDLogLevel obsddLogLevel = OBSDDLogFlagError | OBSDDLogFlagInfo;
|
*
|
*When OBSLOG_LEVEL_DEF is defined as obsddLogLevel.
|
*
|
*Flags may also be consulted when writing custom log formatters,
|
*as the OBSDDLogMessage class captures the individual flag that caused the log message to fire.
|
*
|
*-- Levels --
|
*
|
*Log levels are simply the proper bitmask of the flags.
|
*
|
*-- Booleans --
|
*
|
*The booleans may be used when your logging code involves more than one line.
|
*For example:
|
*
|
*if (OBSLOG_VERBOSE) {
|
* for (id sprocket in sprockets)
|
* OBSDDLogVerbose(@"sprocket: %@", [sprocket description])
|
*}
|
*
|
*-- Async --
|
*
|
*Defines the default asynchronous options.
|
*The default philosophy for asynchronous logging is very simple:
|
*
|
*Log messages with errors should be executed synchronously.
|
* After all, an error just occurred. The application could be unstable.
|
*
|
*All other log messages, such as debug output, are executed asynchronously.
|
* After all, if it wasn't an error, then it was just informational output,
|
* or something the application was easily able to recover from.
|
*
|
*-- Changes --
|
*
|
*You are strongly discouraged from modifying this file.
|
*If you do, you make it more difficult on yourself to merge future bug fixes and improvements from the project.
|
*Instead, create your own MyLogging.h or ApplicationNameLogging.h or CompanyLogging.h
|
*
|
*For an example of customizing your logging experience, see the "Custom Log Levels" page:
|
*Documentation/CustomLogLevels.md
|
**/
|
|
/**
|
* Flags accompany each log. They are used together with levels to filter out logs.
|
*/
|
typedef NS_OPTIONS(NSUInteger, OBSDDLogFlag){
|
/**
|
* 0...00001 OBSDDLogFlagError
|
*/
|
OBSDDLogFlagError = (1 << 0),
|
|
/**
|
* 0...00010 OBSDDLogFlagWarning
|
*/
|
OBSDDLogFlagWarning = (1 << 1),
|
|
/**
|
* 0...00100 OBSDDLogFlagInfo
|
*/
|
OBSDDLogFlagInfo = (1 << 2),
|
|
/**
|
* 0...01000 OBSDDLogFlagDebug
|
*/
|
OBSDDLogFlagDebug = (1 << 3),
|
|
/**
|
* 0...10000 OBSDDLogFlagVerbose
|
*/
|
OBSDDLogFlagVerbose = (1 << 4)
|
};
|
|
/**
|
* Log levels are used to filter out logs. Used together with flags.
|
*/
|
typedef NS_ENUM(NSUInteger, OBSDDLogLevel){
|
/**
|
* No logs
|
*/
|
OBSDDLogLevelOff = 0,
|
|
/**
|
* Error logs only
|
*/
|
OBSDDLogLevelError = (OBSDDLogFlagError),
|
|
/**
|
* Error and warning logs
|
*/
|
OBSDDLogLevelWarning = (OBSDDLogLevelError | OBSDDLogFlagWarning),
|
|
/**
|
* Error, warning and info logs
|
*/
|
OBSDDLogLevelInfo = (OBSDDLogLevelWarning | OBSDDLogFlagInfo),
|
|
/**
|
* Error, warning, info and debug logs
|
*/
|
OBSDDLogLevelDebug = (OBSDDLogLevelInfo | OBSDDLogFlagDebug),
|
|
/**
|
* Error, warning, info, debug and verbose logs
|
*/
|
OBSDDLogLevelVerbose = (OBSDDLogLevelDebug | OBSDDLogFlagVerbose),
|
|
/**
|
* All logs (1...11111)
|
*/
|
OBSDDLogLevelAll = NSUIntegerMax
|
};
|
|
NS_ASSUME_NONNULL_BEGIN
|
|
/**
|
* Extracts just the file name, no path or extension
|
*
|
* @param filePath input file path
|
* @param copy YES if we want the result to be copied
|
*
|
* @return the file name
|
*/
|
NSString *__nullable OBSDDExtractFileNameWithoutExtension(const char *filePath, BOOL copy);
|
|
/**
|
*The THIS_FILE macro gives you an NSString of the file name.
|
*For simplicity and clarity, the file name does not include the full path or file extension.
|
*
|
*For example: OBSDDLogWarn(@"%@: Unable to find thingy", THIS_FILE) -> @"MyViewController: Unable to find thingy"
|
**/
|
#define THIS_FILE (OBSDDExtractFileNameWithoutExtension(__FILE__, NO))
|
|
/**
|
*The THIS_METHOD macro gives you the name of the current objective-c method.
|
*
|
*For example: OBSDDLogWarn(@"%@ - Requires non-nil strings", THIS_METHOD) -> @"setMake:model: requires non-nil strings"
|
*
|
*Note: This does NOT work in straight C functions (non objective-c).
|
*Instead you should use the predefined __FUNCTION__ macro.
|
**/
|
#define THIS_METHOD NSStringFromSelector(_cmd)
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
#pragma mark -
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
/**
|
* The main class, exposes all logging mechanisms, loggers, ...
|
* For most of the users, this class is hidden behind the logging functions like `OBSDDLogInfo`
|
*/
|
@interface OBSDDLog : NSObject
|
|
/**
|
* Returns the singleton `OBSDDLog`.
|
* The instance is used by `OBSDDLog` class methods.
|
*/
|
@property (class, nonatomic, strong, readonly) OBSDDLog *sharedInstance;
|
|
/**
|
*Provides access to the underlying logging queue.
|
*This may be helpful to Logger classes for things like thread synchronization.
|
**/
|
@property (class, nonatomic, DISPATCH_QUEUE_REFERENCE_TYPE, readonly) dispatch_queue_t loggingQueue;
|
|
/**
|
*Logging Primitive.
|
*
|
*This method is used by the macros or logging functions.
|
*It is suggested you stick with the macros as they're easier to use.
|
*
|
* @param asynchronous YES if the logging is done async, NO if you want to force sync
|
* @param level the log level
|
* @param flag the log flag
|
* @param context the context (if any is defined)
|
* @param file the current file
|
* @param function the current function
|
* @param line the current code line
|
* @param tag potential tag
|
* @param format the log format
|
*/
|
+ (void)log:(BOOL)asynchronous
|
level:(OBSDDLogLevel)level
|
flag:(OBSDDLogFlag)flag
|
context:(NSInteger)context
|
file:(const char *)file
|
function:(const char *)function
|
line:(NSUInteger)line
|
tag:(id __nullable)tag
|
format:(NSString *)format, ... NS_FORMAT_FUNCTION(9,10);
|
|
/**
|
*Logging Primitive.
|
*
|
*This method is used by the macros or logging functions.
|
*It is suggested you stick with the macros as they're easier to use.
|
*
|
* @param asynchronous YES if the logging is done async, NO if you want to force sync
|
* @param level the log level
|
* @param flag the log flag
|
* @param context the context (if any is defined)
|
* @param file the current file
|
* @param function the current function
|
* @param line the current code line
|
* @param tag potential tag
|
* @param format the log format
|
*/
|
- (void)log:(BOOL)asynchronous
|
level:(OBSDDLogLevel)level
|
flag:(OBSDDLogFlag)flag
|
context:(NSInteger)context
|
file:(const char *)file
|
function:(const char *)function
|
line:(NSUInteger)line
|
tag:(id __nullable)tag
|
format:(NSString *)format, ... NS_FORMAT_FUNCTION(9,10);
|
|
/**
|
*Logging Primitive.
|
*
|
*This method can be used if you have a prepared va_list.
|
*Similar to `log:level:flag:context:file:function:line:tag:format:...`
|
*
|
* @param asynchronous YES if the logging is done async, NO if you want to force sync
|
* @param level the log level
|
* @param flag the log flag
|
* @param context the context (if any is defined)
|
* @param file the current file
|
* @param function the current function
|
* @param line the current code line
|
* @param tag potential tag
|
* @param format the log format
|
* @param argList the arguments list as a va_list
|
*/
|
+ (void)log:(BOOL)asynchronous
|
level:(OBSDDLogLevel)level
|
flag:(OBSDDLogFlag)flag
|
context:(NSInteger)context
|
file:(const char *)file
|
function:(const char *)function
|
line:(NSUInteger)line
|
tag:(id __nullable)tag
|
format:(NSString *)format
|
args:(va_list)argList NS_SWIFT_NAME(log(asynchronous:level:flag:context:file:function:line:tag:format:arguments:));
|
|
/**
|
*Logging Primitive.
|
*
|
*This method can be used if you have a prepared va_list.
|
*Similar to `log:level:flag:context:file:function:line:tag:format:...`
|
*
|
* @param asynchronous YES if the logging is done async, NO if you want to force sync
|
* @param level the log level
|
* @param flag the log flag
|
* @param context the context (if any is defined)
|
* @param file the current file
|
* @param function the current function
|
* @param line the current code line
|
* @param tag potential tag
|
* @param format the log format
|
* @param argList the arguments list as a va_list
|
*/
|
- (void)log:(BOOL)asynchronous
|
level:(OBSDDLogLevel)level
|
flag:(OBSDDLogFlag)flag
|
context:(NSInteger)context
|
file:(const char *)file
|
function:(const char *)function
|
line:(NSUInteger)line
|
tag:(id __nullable)tag
|
format:(NSString *)format
|
args:(va_list)argList NS_SWIFT_NAME(log(asynchronous:level:flag:context:file:function:line:tag:format:arguments:));
|
|
/**
|
*Logging Primitive.
|
*
|
*This method can be used if you manualy prepared OBSDDLogMessage.
|
*
|
* @param asynchronous YES if the logging is done async, NO if you want to force sync
|
* @param logMessage the log message stored in a `OBSDDLogMessage` model object
|
*/
|
+ (void)log:(BOOL)asynchronous
|
message:(OBSDDLogMessage *)logMessage NS_SWIFT_NAME(log(asynchronous:message:));
|
|
/**
|
*Logging Primitive.
|
*
|
*This method can be used if you manualy prepared OBSDDLogMessage.
|
*
|
* @param asynchronous YES if the logging is done async, NO if you want to force sync
|
* @param logMessage the log message stored in a `OBSDDLogMessage` model object
|
*/
|
- (void)log:(BOOL)asynchronous
|
message:(OBSDDLogMessage *)logMessage NS_SWIFT_NAME(log(asynchronous:message:));
|
|
/**
|
*Since logging can be asynchronous, there may be times when you want to flush the logs.
|
*The framework invokes this automatically when the application quits.
|
**/
|
+ (void)flushLog;
|
|
/**
|
*Since logging can be asynchronous, there may be times when you want to flush the logs.
|
*The framework invokes this automatically when the application quits.
|
**/
|
- (void)flushLog;
|
|
/**
|
*Loggers
|
*
|
*In order for your log statements to go somewhere, you should create and add a logger.
|
*
|
*You can add multiple loggers in order to direct your log statements to multiple places.
|
*And each logger can be configured separately.
|
*So you could have, for example, verbose logging to the console, but a concise log file with only warnings & errors.
|
**/
|
|
/**
|
*Adds the logger to the system.
|
*
|
*This is equivalent to invoking `[OBSDDLog addLogger:logger withLogLevel:OBSDDLogLevelAll]`.
|
**/
|
+ (void)addLogger:(id <OBSDDLogger>)logger;
|
|
/**
|
*Adds the logger to the system.
|
*
|
*This is equivalent to invoking `[OBSDDLog addLogger:logger withLogLevel:OBSDDLogLevelAll]`.
|
**/
|
- (void)addLogger:(id <OBSDDLogger>)logger;
|
|
/**
|
*Adds the logger to the system.
|
*
|
*The level that you provide here is a preemptive filter (for performance).
|
*That is, the level specified here will be used to filter out logMessages so that
|
*the logger is never even invoked for the messages.
|
*
|
*More information:
|
*When you issue a log statement, the logging framework iterates over each logger,
|
*and checks to see if it should forward the logMessage to the logger.
|
*This check is done using the level parameter passed to this method.
|
*
|
*For example:
|
*
|
*`[OBSDDLog addLogger:consoleLogger withLogLevel:OBSDDLogLevelVerbose];`
|
*`[OBSDDLog addLogger:fileLogger withLogLevel:OBSDDLogLevelWarning];`
|
*
|
*`OBSDDLogError(@"oh no");` => gets forwarded to consoleLogger & fileLogger
|
*`OBSDDLogInfo(@"hi");` => gets forwarded to consoleLogger only
|
*
|
*It is important to remember that Lumberjack uses a BITMASK.
|
*Many developers & third party frameworks may define extra log levels & flags.
|
*For example:
|
*
|
*`#define SOME_FRAMEWORK_LOG_FLAG_TRACE (1 << 6) // 0...1000000`
|
*
|
*So if you specify `OBSDDLogLevelVerbose` to this method, you won't see the framework's trace messages.
|
*
|
*`(SOME_FRAMEWORK_LOG_FLAG_TRACE & OBSDDLogLevelVerbose) => (01000000 & 00011111) => NO`
|
*
|
*Consider passing `OBSDDLogLevelAll` to this method, which has all bits set.
|
*You can also use the exclusive-or bitwise operator to get a bitmask that has all flags set,
|
*except the ones you explicitly don't want. For example, if you wanted everything except verbose & debug:
|
*
|
*`((OBSDDLogLevelAll ^ OBSDDLogLevelVerbose) | OBSDDLogLevelInfo)`
|
**/
|
+ (void)addLogger:(id <OBSDDLogger>)logger withLevel:(OBSDDLogLevel)level;
|
|
/**
|
*Adds the logger to the system.
|
*
|
*The level that you provide here is a preemptive filter (for performance).
|
*That is, the level specified here will be used to filter out logMessages so that
|
*the logger is never even invoked for the messages.
|
*
|
*More information:
|
*When you issue a log statement, the logging framework iterates over each logger,
|
*and checks to see if it should forward the logMessage to the logger.
|
*This check is done using the level parameter passed to this method.
|
*
|
*For example:
|
*
|
*`[OBSDDLog addLogger:consoleLogger withLogLevel:OBSDDLogLevelVerbose];`
|
*`[OBSDDLog addLogger:fileLogger withLogLevel:OBSDDLogLevelWarning];`
|
*
|
*`OBSDDLogError(@"oh no");` => gets forwarded to consoleLogger & fileLogger
|
*`OBSDDLogInfo(@"hi");` => gets forwarded to consoleLogger only
|
*
|
*It is important to remember that Lumberjack uses a BITMASK.
|
*Many developers & third party frameworks may define extra log levels & flags.
|
*For example:
|
*
|
*`#define SOME_FRAMEWORK_LOG_FLAG_TRACE (1 << 6) // 0...1000000`
|
*
|
*So if you specify `OBSDDLogLevelVerbose` to this method, you won't see the framework's trace messages.
|
*
|
*`(SOME_FRAMEWORK_LOG_FLAG_TRACE & OBSDDLogLevelVerbose) => (01000000 & 00011111) => NO`
|
*
|
*Consider passing `OBSDDLogLevelAll` to this method, which has all bits set.
|
*You can also use the exclusive-or bitwise operator to get a bitmask that has all flags set,
|
*except the ones you explicitly don't want. For example, if you wanted everything except verbose & debug:
|
*
|
*`((OBSDDLogLevelAll ^ OBSDDLogLevelVerbose) | OBSDDLogLevelInfo)`
|
**/
|
- (void)addLogger:(id <OBSDDLogger>)logger withLevel:(OBSDDLogLevel)level;
|
|
/**
|
* Remove the logger from the system
|
*/
|
+ (void)removeLogger:(id <OBSDDLogger>)logger;
|
|
/**
|
* Remove the logger from the system
|
*/
|
- (void)removeLogger:(id <OBSDDLogger>)logger;
|
|
/**
|
* Remove all the current loggers
|
*/
|
+ (void)removeAllLoggers;
|
|
/**
|
* Remove all the current loggers
|
*/
|
- (void)removeAllLoggers;
|
|
/**
|
* Return all the current loggers
|
*/
|
@property (class, nonatomic, copy, readonly) NSArray<id<OBSDDLogger>> *allLoggers;
|
|
/**
|
* Return all the current loggers
|
*/
|
@property (nonatomic, copy, readonly) NSArray<id<OBSDDLogger>> *allLoggers;
|
|
/**
|
* Return all the current loggers with their level (aka OBSDDLoggerInformation).
|
*/
|
@property (class, nonatomic, copy, readonly) NSArray<OBSDDLoggerInformation *> *allLoggersWithLevel;
|
|
/**
|
* Return all the current loggers with their level (aka OBSDDLoggerInformation).
|
*/
|
@property (nonatomic, copy, readonly) NSArray<OBSDDLoggerInformation *> *allLoggersWithLevel;
|
|
/**
|
*Registered Dynamic Logging
|
*
|
*These methods allow you to obtain a list of classes that are using registered dynamic logging,
|
*and also provides methods to get and set their log level during run time.
|
**/
|
|
/**
|
* Returns an array with the classes that are using registered dynamic logging
|
*/
|
@property (class, nonatomic, copy, readonly) NSArray<Class> *registeredClasses;
|
|
/**
|
* Returns an array with the classes names that are using registered dynamic logging
|
*/
|
@property (class, nonatomic, copy, readonly) NSArray<NSString*> *registeredClassNames;
|
|
/**
|
* Returns the current log level for a certain class
|
*
|
* @param aClass `Class` param
|
*/
|
+ (OBSDDLogLevel)levelForClass:(Class)aClass;
|
|
/**
|
* Returns the current log level for a certain class
|
*
|
* @param aClassName string param
|
*/
|
+ (OBSDDLogLevel)levelForClassWithName:(NSString *)aClassName;
|
|
/**
|
* Set the log level for a certain class
|
*
|
* @param level the new level
|
* @param aClass `Class` param
|
*/
|
+ (void)setLevel:(OBSDDLogLevel)level forClass:(Class)aClass;
|
|
/**
|
* Set the log level for a certain class
|
*
|
* @param level the new level
|
* @param aClassName string param
|
*/
|
+ (void)setLevel:(OBSDDLogLevel)level forClassWithName:(NSString *)aClassName;
|
|
@end
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
#pragma mark -
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
/**
|
* This protocol describes a basic logger behavior.
|
* Basically, it can log messages, store a logFormatter plus a bunch of optional behaviors.
|
* (i.e. flush, get its loggerQueue, get its name, ...
|
*/
|
@protocol OBSDDLogger <NSObject>
|
|
/**
|
* The log message method
|
*
|
* @param logMessage the message (model)
|
*/
|
- (void)logMessage:(OBSDDLogMessage *)logMessage NS_SWIFT_NAME(log(message:));
|
|
/**
|
*Formatters may optionally be added to any logger.
|
*
|
*If no formatter is set, the logger simply logs the message as it is given in logMessage,
|
*or it may use its own built in formatting style.
|
**/
|
@property (nonatomic, strong) id <OBSDDLogFormatter> logFormatter;
|
|
@optional
|
|
/**
|
*Since logging is asynchronous, adding and removing loggers is also asynchronous.
|
*In other words, the loggers are added and removed at appropriate times with regards to log messages.
|
*
|
*- Loggers will not receive log messages that were executed prior to when they were added.
|
*- Loggers will not receive log messages that were executed after they were removed.
|
*
|
*These methods are executed in the logging thread/queue.
|
*This is the same thread/queue that will execute every logMessage: invocation.
|
*Loggers may use these methods for thread synchronization or other setup/teardown tasks.
|
**/
|
- (void)didAddLogger;
|
|
/**
|
*Since logging is asynchronous, adding and removing loggers is also asynchronous.
|
*In other words, the loggers are added and removed at appropriate times with regards to log messages.
|
*
|
*- Loggers will not receive log messages that were executed prior to when they were added.
|
*- Loggers will not receive log messages that were executed after they were removed.
|
*
|
*These methods are executed in the logging thread/queue given in parameter.
|
*This is the same thread/queue that will execute every logMessage: invocation.
|
*Loggers may use the queue parameter to set specific values on the queue with dispatch_set_specific() function.
|
**/
|
- (void)didAddLoggerInQueue:(dispatch_queue_t)queue;
|
|
/**
|
* See the above description for `didAddLoger`
|
*/
|
- (void)willRemoveLogger;
|
|
/**
|
*Some loggers may buffer IO for optimization purposes.
|
*For example, a database logger may only save occasionaly as the disk IO is slow.
|
*In such loggers, this method should be implemented to flush any pending IO.
|
*
|
*This allows invocations of OBSDDLog's flushLog method to be propogated to loggers that need it.
|
*
|
*Note that OBSDDLog's flushLog method is invoked automatically when the application quits,
|
*and it may be also invoked manually by the developer prior to application crashes, or other such reasons.
|
**/
|
- (void)flush;
|
|
/**
|
*Each logger is executed concurrently with respect to the other loggers.
|
*Thus, a dedicated dispatch queue is used for each logger.
|
*Logger implementations may optionally choose to provide their own dispatch queue.
|
**/
|
@property (nonatomic, DISPATCH_QUEUE_REFERENCE_TYPE, readonly) dispatch_queue_t loggerQueue;
|
|
/**
|
*If the logger implementation does not choose to provide its own queue,
|
*one will automatically be created for it.
|
*The created queue will receive its name from this method.
|
*This may be helpful for debugging or profiling reasons.
|
**/
|
@property (nonatomic, readonly) NSString *loggerName;
|
|
@end
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
#pragma mark -
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
/**
|
* This protocol describes the behavior of a log formatter
|
*/
|
@protocol OBSDDLogFormatter <NSObject>
|
@required
|
|
/**
|
*Formatters may optionally be added to any logger.
|
*This allows for increased flexibility in the logging environment.
|
*For example, log messages for log files may be formatted differently than log messages for the console.
|
*
|
*For more information about formatters, see the "Custom Formatters" page:
|
*Documentation/CustomFormatters.md
|
*
|
*The formatter may also optionally filter the log message by returning nil,
|
*in which case the logger will not log the message.
|
**/
|
- (NSString *__nullable)formatLogMessage:(OBSDDLogMessage *)logMessage NS_SWIFT_NAME(format(message:));
|
|
@optional
|
|
/**
|
*A single formatter instance can be added to multiple loggers.
|
*These methods provides hooks to notify the formatter of when it's added/removed.
|
*
|
*This is primarily for thread-safety.
|
*If a formatter is explicitly not thread-safe, it may wish to throw an exception if added to multiple loggers.
|
*Or if a formatter has potentially thread-unsafe code (e.g. NSDateFormatter),
|
*it could possibly use these hooks to switch to thread-safe versions of the code.
|
**/
|
- (void)didAddToLogger:(id <OBSDDLogger>)logger;
|
|
/**
|
*A single formatter instance can be added to multiple loggers.
|
*These methods provides hooks to notify the formatter of when it's added/removed.
|
*
|
*This is primarily for thread-safety.
|
*If a formatter is explicitly not thread-safe, it may wish to throw an exception if added to multiple loggers.
|
*Or if a formatter has potentially thread-unsafe code (e.g. NSDateFormatter),
|
*it could possibly use these hooks to switch to thread-safe versions of the code or use dispatch_set_specific()
|
. *to add its own specific values.
|
**/
|
- (void)didAddToLogger:(id <OBSDDLogger>)logger inQueue:(dispatch_queue_t)queue;
|
|
/**
|
* See the above description for `didAddToLogger:`
|
*/
|
- (void)willRemoveFromLogger:(id <OBSDDLogger>)logger;
|
|
@end
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
#pragma mark -
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
/**
|
* This protocol describes a dynamic logging component
|
*/
|
@protocol OBSDDRegisteredDynamicLogging
|
|
/**
|
*Implement these methods to allow a file's log level to be managed from a central location.
|
*
|
*This is useful if you'd like to be able to change log levels for various parts
|
*of your code from within the running application.
|
*
|
*Imagine pulling up the settings for your application,
|
*and being able to configure the logging level on a per file basis.
|
*
|
*The implementation can be very straight-forward:
|
*
|
*```
|
*+ (int)obsddLogLevel
|
*{
|
* return obsddLogLevel;
|
*}
|
*
|
*+ (void)ddSetLogLevel:(OBSDDLogLevel)level
|
*{
|
* obsddLogLevel = level;
|
*}
|
*```
|
**/
|
@property (class, nonatomic, readwrite, setter=ddSetLogLevel:) OBSDDLogLevel obsddLogLevel;
|
|
@end
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
#pragma mark -
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
#ifndef NS_DESIGNATED_INITIALIZER
|
#define NS_DESIGNATED_INITIALIZER
|
#endif
|
|
/**
|
* Log message options, allow copying certain log elements
|
*/
|
typedef NS_OPTIONS(NSInteger, OBSDDLogMessageOptions){
|
/**
|
* Use this to use a copy of the file path
|
*/
|
OBSDDLogMessageCopyFile = 1 << 0,
|
/**
|
* Use this to use a copy of the function name
|
*/
|
OBSDDLogMessageCopyFunction = 1 << 1,
|
/**
|
* Use this to use avoid a copy of the message
|
*/
|
OBSDDLogMessageDontCopyMessage = 1 << 2
|
};
|
|
/**
|
*The `OBSDDLogMessage` class encapsulates information about the log message.
|
*If you write custom loggers or formatters, you will be dealing with objects of this class.
|
**/
|
@interface OBSDDLogMessage : NSObject <NSCopying>
|
{
|
// Direct accessors to be used only for performance
|
@public
|
NSString *_message;
|
OBSDDLogLevel _level;
|
OBSDDLogFlag _flag;
|
NSInteger _context;
|
NSString *_file;
|
NSString *_fileName;
|
NSString *_function;
|
NSUInteger _line;
|
id _tag;
|
OBSDDLogMessageOptions _options;
|
NSDate *_timestamp;
|
NSString *_threadID;
|
NSString *_threadName;
|
NSString *_queueLabel;
|
}
|
|
/**
|
* Default `init` for empty messages.
|
*/
|
- (instancetype)init NS_DESIGNATED_INITIALIZER;
|
|
/**
|
*Standard init method for a log message object.
|
*Used by the logging primitives. (And the macros use the logging primitives.)
|
*
|
*If you find need to manually create logMessage objects, there is one thing you should be aware of:
|
*
|
*If no flags are passed, the method expects the file and function parameters to be string literals.
|
*That is, it expects the given strings to exist for the duration of the object's lifetime,
|
*and it expects the given strings to be immutable.
|
*In other words, it does not copy these strings, it simply points to them.
|
*This is due to the fact that __FILE__ and __FUNCTION__ are usually used to specify these parameters,
|
*so it makes sense to optimize and skip the unnecessary allocations.
|
*However, if you need them to be copied you may use the options parameter to specify this.
|
*
|
* @param message the message
|
* @param level the log level
|
* @param flag the log flag
|
* @param context the context (if any is defined)
|
* @param file the current file
|
* @param function the current function
|
* @param line the current code line
|
* @param tag potential tag
|
* @param options a bitmask which supports OBSDDLogMessageCopyFile and OBSDDLogMessageCopyFunction.
|
* @param timestamp the log timestamp
|
*
|
* @return a new instance of a log message model object
|
*/
|
- (instancetype)initWithMessage:(NSString *)message
|
level:(OBSDDLogLevel)level
|
flag:(OBSDDLogFlag)flag
|
context:(NSInteger)context
|
file:(NSString *)file
|
function:(NSString *__nullable)function
|
line:(NSUInteger)line
|
tag:(id __nullable)tag
|
options:(OBSDDLogMessageOptions)options
|
timestamp:(NSDate *__nullable)timestamp NS_DESIGNATED_INITIALIZER;
|
|
/**
|
*Read-only properties
|
**/
|
|
/**
|
* The log message
|
*/
|
@property (readonly, nonatomic) NSString *message;
|
@property (readonly, nonatomic) OBSDDLogLevel level;
|
@property (readonly, nonatomic) OBSDDLogFlag flag;
|
@property (readonly, nonatomic) NSInteger context;
|
@property (readonly, nonatomic) NSString *file;
|
@property (readonly, nonatomic) NSString *fileName;
|
@property (readonly, nonatomic) NSString *__nullable function;
|
@property (readonly, nonatomic) NSUInteger line;
|
@property (readonly, nonatomic) id __nullable tag;
|
@property (readonly, nonatomic) OBSDDLogMessageOptions options;
|
@property (readonly, nonatomic) NSDate *timestamp;
|
@property (readonly, nonatomic) NSString *threadID; // g_ID as it appears in NSLog calculated from the machThreadID
|
@property (readonly, nonatomic) NSString *threadName;
|
@property (readonly, nonatomic) NSString *queueLabel;
|
|
@end
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
#pragma mark -
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
/**
|
*The `OBSDDLogger` protocol specifies that an optional formatter can be added to a logger.
|
*Most (but not all) loggers will want to support formatters.
|
*
|
*However, writting getters and setters in a thread safe manner,
|
*while still maintaining maximum speed for the logging process, is a difficult task.
|
*
|
*To do it right, the implementation of the getter/setter has strict requiremenets:
|
*- Must NOT require the `logMessage:` method to acquire a lock.
|
*- Must NOT require the `logMessage:` method to access an atomic property (also a lock of sorts).
|
*
|
*To simplify things, an abstract logger is provided that implements the getter and setter.
|
*
|
*Logger implementations may simply extend this class,
|
*and they can ACCESS THE FORMATTER VARIABLE DIRECTLY from within their `logMessage:` method!
|
**/
|
@interface OBSDDAbstractLogger : NSObject <OBSDDLogger>
|
{
|
// Direct accessors to be used only for performance
|
@public
|
id <OBSDDLogFormatter> _logFormatter;
|
dispatch_queue_t _loggerQueue;
|
}
|
|
@property (nonatomic, strong, nullable) id <OBSDDLogFormatter> logFormatter;
|
@property (nonatomic, DISPATCH_QUEUE_REFERENCE_TYPE) dispatch_queue_t loggerQueue;
|
|
// For thread-safety assertions
|
|
/**
|
* Return YES if the current logger uses a global queue for logging
|
*/
|
@property (nonatomic, readonly, getter=isOnGlobalLoggingQueue) BOOL onGlobalLoggingQueue;
|
|
/**
|
* Return YES if the current logger uses the internal designated queue for logging
|
*/
|
@property (nonatomic, readonly, getter=isOnInternalLoggerQueue) BOOL onInternalLoggerQueue;
|
|
@end
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
#pragma mark -
|
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
@interface OBSDDLoggerInformation : NSObject
|
|
@property (nonatomic, readonly) id <OBSDDLogger> logger;
|
@property (nonatomic, readonly) OBSDDLogLevel level;
|
|
+ (OBSDDLoggerInformation *)informationWithLogger:(id <OBSDDLogger>)logger
|
andLevel:(OBSDDLogLevel)level;
|
|
@end
|
|
NS_ASSUME_NONNULL_END
|
