mirror of
https://github.com/servalproject/serval-dna.git
synced 2024-12-21 14:07:53 +00:00
93 lines
4.2 KiB
C
93 lines
4.2 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
|
|
#include <alloca.h>
|
|
#include "xprintf.h"
|
|
|
|
/*
|
|
* 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__)
|
|
|
|
void xprint_sourceloc(XPRINTF, struct __sourceloc);
|
|
|
|
#define alloca_str_sourceloc(s) (sourceloc_tostr(alloca(sourceloc_tostr_len(s) + 1), (s)))
|
|
|
|
extern char *sourceloc_tostr(char *dstStr, ssize_t dstBufSiz, struct __sourceloc);
|
|
extern size_t sourceloc_tostr_len(struct __sourceloc);
|
|
|
|
#endif // __SERVAL_DNA__WHENCE_H
|