mirror of
https://github.com/servalproject/serval-dna.git
synced 2024-12-24 07:16:43 +00:00
84 lines
3.9 KiB
C
84 lines
3.9 KiB
C
|
/*
|
||
|
Copyright (C) 2012 Serval Project Inc.
|
||
|
|
||
|
This program is free software; you can redistribute it and/or
|
||
|
modify it under the terms of the GNU General Public License
|
||
|
as published by the Free Software Foundation; either version 2
|
||
|
of the License, or (at your option) any later version.
|
||
|
|
||
|
This program is distributed in the hope that it will be useful,
|
||
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
|
GNU General Public License for more details.
|
||
|
|
||
|
You should have received a copy of the GNU General Public License
|
||
|
along with this program; if not, write to the Free Software
|
||
|
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
||
|
*/
|
||
|
|
||
|
#ifndef __SERVAL_DNA__WHENCE_H
|
||
|
#define __SERVAL_DNA__WHENCE_H
|
||
|
|
||
|
#include <stdio.h> // for NULL
|
||
|
|
||
|
/*
|
||
|
* Every log message identifies the location in the source code at which the
|
||
|
* message was produced. This location is represented by a struct __sourceloc,
|
||
|
* which is passed by value to the logMessage() function and its ilk.
|
||
|
*
|
||
|
* A struct __sourceloc value is generated by the __HERE__ macro, which uses
|
||
|
* the cpp(1) built-in macros __FILE__, __LINE__ and __FUNCTION__ to generate
|
||
|
* its elements. The __NOWHERE__ macro creates a struct __sourceloc with NULL
|
||
|
* and zero fields. If you pass __NOWHERE__ to logMessage(), it will omit
|
||
|
* location information from the log line. The __NOWHENCE__ macro creates a
|
||
|
* special source __sourceloc that logging primitives should interpret to
|
||
|
* suppress the output of the usual source-code location information.
|
||
|
*
|
||
|
* Sometimes, a function wants to log a message as though its caller were the
|
||
|
* origin of the message. This is typical of "primitive" type functions that
|
||
|
* are used in many places throughout the code, and whose internal workings are
|
||
|
* generally well-debugged and of little interest for ongoing development. In
|
||
|
* this case, the code pattern is to declare the underscore-prefixed function
|
||
|
* as taking a struct __sourceloc argument, and a macro that invokes the
|
||
|
* function, passing the __HERE__ macro for that argument:
|
||
|
*
|
||
|
* int _primitive(struct __sourceloc __whence, int arg1, const char *arg2);
|
||
|
*
|
||
|
* #define primitive(arg1, arg2) _primitive(__HERE__, (arg1), (arg2))
|
||
|
*
|
||
|
* Within the _primitive() function, the standard logging macros defined below
|
||
|
* (WHYF(), WARNF(), INFOF(), DEBUGF() etc.) will use the __whence argument
|
||
|
* instead of __HERE__ when logging their message. This is achieved using a
|
||
|
* dirty trick: in the function *definition*, the __sourceloc argument MUST be
|
||
|
* named '__whence'. The trick is that there is a global variable called
|
||
|
* '__whence' which always contains the value of __NOWHERE__. If that variable
|
||
|
* is lexically obscured by a local variable or parameter called '__whence',
|
||
|
* then the DEBUG macros will use __whence, otherwise they will use __HERE__.
|
||
|
* This logic is encapsulated in the __WHENCE__ macro, to make it available to
|
||
|
* for other purposes. For example, a better definition of the primitive()
|
||
|
* macro above would be:
|
||
|
*
|
||
|
* #define primitive(arg1, arg2) _primitive(__WHENCE__, (arg1), (arg2))
|
||
|
*
|
||
|
* Then, if it were invoked from within another primitive-type function, it
|
||
|
* would log messages with the __sourceloc of that primitive's caller, which is
|
||
|
* probably the most useful for diagnosis.
|
||
|
*
|
||
|
* @author Andrew Bettison <andrew@servalproject.com>
|
||
|
*/
|
||
|
|
||
|
struct __sourceloc {
|
||
|
const char *file;
|
||
|
unsigned int line;
|
||
|
const char *function;
|
||
|
};
|
||
|
|
||
|
extern const struct __sourceloc __whence; // see above
|
||
|
|
||
|
#define __HERE__ ((struct __sourceloc){ .file = __FILE__, .line = __LINE__, .function = __FUNCTION__ })
|
||
|
#define __NOWHERE__ ((struct __sourceloc){ .file = NULL, .line = 0, .function = NULL })
|
||
|
#define __NOWHENCE__ ((struct __sourceloc){ .file = "", .line = 0, .function = NULL })
|
||
|
#define __WHENCE__ (__whence.file ? __whence : __HERE__)
|
||
|
|
||
|
#endif // __SERVAL_DNA__WHENCE_H
|