summaryrefslogtreecommitdiffstats
path: root/include/sal/log.hxx
diff options
context:
space:
mode:
Diffstat (limited to 'include/sal/log.hxx')
-rw-r--r--include/sal/log.hxx385
1 files changed, 385 insertions, 0 deletions
diff --git a/include/sal/log.hxx b/include/sal/log.hxx
new file mode 100644
index 000000000..00d533ab5
--- /dev/null
+++ b/include/sal/log.hxx
@@ -0,0 +1,385 @@
+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+
+#ifndef INCLUDED_SAL_LOG_HXX
+#define INCLUDED_SAL_LOG_HXX
+
+#include "sal/config.h"
+
+#include <cstdlib>
+#include <sstream>
+#include <string>
+
+#include "sal/detail/log.h"
+#include "sal/saldllapi.h"
+#include "sal/types.h"
+
+// Avoid the use of other sal code in this header as much as possible, so that
+// this code can be called from other sal code without causing endless
+// recursion.
+
+/// @cond INTERNAL
+
+extern "C" SAL_DLLPUBLIC void SAL_CALL sal_detail_log(
+ sal_detail_LogLevel level, char const * area, char const * where,
+ char const * message, sal_uInt32 backtraceDepth);
+
+extern "C" SAL_DLLPUBLIC sal_Bool SAL_CALL sal_detail_log_report(
+ sal_detail_LogLevel level, char const * area);
+
+namespace sal { namespace detail {
+
+inline void log(
+ sal_detail_LogLevel level, char const * area, char const * where,
+ std::ostringstream const & stream, sal_uInt32 backtraceDepth)
+{
+ // An alternative would be to have sal_detail_log take a std::ostringstream
+ // pointer (via a C void pointer); the advantage would be smaller client
+ // code (the ".str().c_str()" part would move into the implementation of
+ // sal_detail_log) and potential for proper support of embedded null
+ // characters within the message, but the disadvantage would be dependence
+ // on the C++ ABI; as a compromise, the ".str().c_str()" part has been moved
+ // to this inline function so that it is potentially only emitted once per
+ // dynamic library:
+ sal_detail_log(level, area, where, stream.str().c_str(), backtraceDepth);
+}
+
+// Special handling of the common case where the message consists of just a
+// string literal, to produce smaller call-site code:
+
+struct StreamStart {};
+
+struct StreamString {
+ StreamString(char const * s): string(s) {}
+
+ char const * string;
+
+ typedef char Result;
+};
+
+struct StreamIgnore {
+ typedef struct { char a[2]; } Result;
+};
+
+inline StreamString operator <<(
+ SAL_UNUSED_PARAMETER StreamStart const &, char const * s)
+{
+ return StreamString(s);
+}
+
+template< typename T > inline StreamIgnore operator <<(
+ SAL_UNUSED_PARAMETER StreamStart const &, SAL_UNUSED_PARAMETER T const &)
+{
+ std::abort();
+#if defined _MSC_VER && _MSC_VER < 1700
+ return StreamIgnore();
+#endif
+}
+
+template< typename T > inline StreamIgnore operator <<(
+ SAL_UNUSED_PARAMETER StreamString const &, SAL_UNUSED_PARAMETER T const &)
+{
+ std::abort();
+#if defined _MSC_VER && _MSC_VER < 1700
+ return StreamIgnore();
+#endif
+}
+
+template< typename T > inline StreamIgnore operator <<(
+ SAL_UNUSED_PARAMETER StreamIgnore const &, SAL_UNUSED_PARAMETER T const &)
+{
+ std::abort();
+#if defined _MSC_VER && _MSC_VER < 1700
+ return StreamIgnore();
+#endif
+}
+
+template< typename T > typename T::Result getResult(T const &);
+
+inline char const * unwrapStream(StreamString const & s) { return s.string; }
+
+inline char const * unwrapStream(SAL_UNUSED_PARAMETER StreamIgnore const &) {
+ std::abort();
+#if defined _MSC_VER && _MSC_VER < 1700
+ return 0;
+#endif
+}
+
+} }
+
+#define SAL_DETAIL_LOG_STREAM(condition, level, area, where, stream) \
+ do { \
+ if ((condition) && sal_detail_log_report(level, area)) { \
+ if (sizeof ::sal::detail::getResult( \
+ ::sal::detail::StreamStart() << stream) == 1) \
+ { \
+ ::sal_detail_log( \
+ (level), (area), (where), \
+ ::sal::detail::unwrapStream( \
+ ::sal::detail::StreamStart() << stream), \
+ 0); \
+ } else { \
+ ::std::ostringstream sal_detail_stream; \
+ sal_detail_stream << stream; \
+ ::sal::detail::log( \
+ (level), (area), (where), sal_detail_stream, 0); \
+ } \
+ } \
+ } while (false)
+
+/// @endcond
+
+/** A simple macro to create a "file and line number" string.
+
+ Potentially not only useful within the log framework (where it is used
+ automatically), but also when creating exception messages.
+
+ @attention For now, this functionality should only be used internally within
+ LibreOffice. It may change again in a future version.
+
+ @since LibreOffice 3.5
+*/
+#define SAL_WHERE SAL_DETAIL_WHERE
+
+/** A facility for generating temporary string messages by piping items into a
+ C++ std::ostringstream.
+
+ This can be useful for example in a call to SAL_INFO when depending on some
+ boolean condition data of incompatible types shall be streamed into the
+ message, as in:
+
+ SAL_INFO("foo", "object: " << (hasName ? obj->name : SAL_STREAM(obj)));
+
+ @attention For now, this functionality should only be used internally within
+ LibreOffice. It may change again in a future version.
+
+ @since LibreOffice 3.5
+*/
+#if defined _LIBCPP_VERSION || (defined _MSC_VER && _MSC_VER >= 1915)
+#define SAL_STREAM(stream) \
+ (::std::ostringstream() << stream).str()
+#else
+#define SAL_STREAM(stream) \
+ (dynamic_cast< ::std::ostringstream & >(::std::ostringstream() << stream).str())
+#endif
+
+/**
+ @page sal_log Basic logging functionality.
+
+ @short Macros for logging.
+
+ SAL_INFO(char const * area, expr),
+ SAL_INFO_IF(bool condition, char const * area, expr),
+ SAL_WARN(char const * area, expr),
+ SAL_WARN_IF(bool condition, char const * area, expr), and SAL_DEBUG(expr)
+ produce an info, warning, or debug log entry with a message produced by
+ piping items into a C++ std::ostringstream. The given expr must be so that
+ the full expression "stream << expr" is valid, where stream is a variable of
+ type std::ostringstream.
+
+ SAL_INFO("foo", "string " << s << " of length " << n)
+
+ would be an example of such a call.
+
+ The composed message should be in UTF-8 and it should contain no vertical
+ formatting characters and no null characters
+
+ For the _IF variants, log output is only generated if the given condition is
+ true (in addition to the other conditions that have to be met).
+
+ The SAL_DEBUG macro is for temporary debug statements that are used while
+ working on code. It is never meant to remain in the code. It will always
+ simply output the given expression in debug builds.
+
+ For all the other macros, the given area argument must be non-null and must
+ match the regular expression
+
+ @verbatim
+ <area> ::= <segment>("."<segment>)*
+ @endverbatim
+
+ with
+
+ @verbatim
+ <segment> ::= [0-9a-z]+
+ @endverbatim
+
+ For a list of areas used see @ref sal_log_areas "SAL debug areas". Whenever
+ you use a new log area, add it to the file include/sal/log-areas.dox .
+
+ Whether these macros generate any log output is controlled in a two-stage
+ process.
+
+ First, at compile time the macros SAL_LOG_INFO and SAL_LOG_WARN,
+ respectively, control whether the INFO and WARN macros, respectively,
+ expand to actual code (in case the macro is defined, to any value) or to
+ no-ops (in case the macro is not defined).
+
+ Second, at runtime the environment variable SAL_LOG further limits which
+ macro calls actually generate log output. The environment variable SAL_LOG
+ must either be unset or must match the regular expression
+
+ @verbatim
+ <env> ::= <switch>*
+ @endverbatim
+
+ with
+
+ @verbatim
+ <switch> ::= <sense><item>
+ <sense> ::= "+"|"-"
+ <item> ::= <flag>|<level>("."<area>)?
+ <flag> ::= "TIMESTAMP"|"RELATIVETIMER"
+ <level> ::= "INFO"|"WARN"
+ @endverbatim
+
+ If the environment variable is unset, the setting "+WARN" is
+ assumed instead (which results in all warnings being output but no
+ infos). If the given value does not match the regular expression,
+ "+INFO+WARN" is used instead (which in turn results in everything
+ being output).
+
+ The "+TIMESTAMP" flag causes each output line (as selected by the level
+ switch(es)) to be prefixed by a timestamp like 2016-08-18:14:04:43.
+
+ The "+RELATIVETIMER" flag causes each output line (as selected by
+ the level switch(es)) to be prefixed by a relative timestamp in
+ seconds since the first output line like 1.312.
+
+ If both +TIMESTAMP and +RELATIVETIMER are specified, they are
+ output in that order.
+
+ Specifying a flag with a negative sense has no effect. Specifying
+ the same flag multiple times has no extra effect.
+
+ A given macro call's level (INFO or WARN) and area is matched against the
+ given switches as follows: Only those switches for which the level matches
+ the given level and for which the area is a prefix (including both empty and
+ full prefixes) of the given area are considered. Log output is generated if
+ and only if among the longest such switches (if any), there is at least one
+ that has a sense of "+". (That is, if both +INFO.foo and -INFO.foo are
+ present, +INFO.foo wins.)
+
+ If no WARN selection is specified, but an INFO selection is, the
+ INFO selection is used for WARN messages, too.
+
+ For example, if SAL_LOG is "+INFO-INFO.foo+INFO.foo.bar", then calls like
+ SAL_INFO("foo.bar", ...), SAL_INFO("foo.bar.baz", ...), or
+ SAL_INFO("other", ...) generate output, while calls like
+ SAL_INFO("foo", ...) or SAL_INFO("foo.barzzz", ...) do not.
+
+ The generated log output consists of the optional timestamp, the given level
+ ("info" or "warn"), the given area, the process ID, the thread ID, the
+ source file, and the source line number, each followed by a colon, followed
+ by a space, the given message, and a newline. The precise format of the log
+ output is subject to change. The log output is printed to stderr without
+ further text encoding conversion.
+
+ On some systems, log output can be redirected to other log sinks,
+ notably a file provided as a system path and filename via
+ environment variable SAL_LOG_FILE; or to a syslog facility if
+ LibreOffice is suitably built, by setting environment variable
+ SAL_LOG_SYSLOG.
+
+ @see @ref sal_log_areas
+
+ @attention For now, this functionality should only be used internally within
+ LibreOffice. It may change again in a future version.
+
+ @since LibreOffice 3.5
+*/
+
+/**
+ Produce log entry from stream in the given log area.
+
+ See @ref sal_log "basic logging functionality" for details.
+*/
+#define SAL_INFO(area, stream) \
+ SAL_DETAIL_LOG_STREAM( \
+ SAL_DETAIL_ENABLE_LOG_INFO, ::SAL_DETAIL_LOG_LEVEL_INFO, area, \
+ SAL_WHERE, stream)
+
+/**
+ Produce log entry from stream in the given log area if condition is true.
+
+ See @ref sal_log "basic logging functionality" for details.
+*/
+#define SAL_INFO_IF(condition, area, stream) \
+ SAL_DETAIL_LOG_STREAM( \
+ SAL_DETAIL_ENABLE_LOG_INFO && (condition), \
+ ::SAL_DETAIL_LOG_LEVEL_INFO, area, SAL_WHERE, stream)
+
+/**
+ Produce warning entry from stream in the given log area.
+
+ See @ref sal_log "basic logging functionality" for details.
+*/
+#define SAL_WARN(area, stream) \
+ SAL_DETAIL_LOG_STREAM( \
+ SAL_DETAIL_ENABLE_LOG_WARN, ::SAL_DETAIL_LOG_LEVEL_WARN, area, \
+ SAL_WHERE, stream)
+
+/**
+ Produce warning entry from stream in the given log area if condition is true.
+
+ See @ref sal_log "basic logging functionality" for details.
+*/
+#define SAL_WARN_IF(condition, area, stream) \
+ SAL_DETAIL_LOG_STREAM( \
+ SAL_DETAIL_ENABLE_LOG_WARN && (condition), \
+ ::SAL_DETAIL_LOG_LEVEL_WARN, area, SAL_WHERE, stream)
+
+/**
+ Produce temporary debugging output from stream. This macro is meant to be
+ used only while working on code and should never exist in production code.
+
+ See @ref sal_log "basic logging functionality" for details.
+*/
+#define SAL_DEBUG(stream) \
+ SAL_DETAIL_LOG_STREAM( \
+ SAL_LOG_TRUE, ::SAL_DETAIL_LOG_LEVEL_DEBUG, NULL, NULL, stream)
+
+/**
+ Produce temporary debugging output from stream along with a backtrace of the
+ calling location.
+
+ This macro is meant to be used only while working on code and should never
+ exist in production code.
+
+ @param stream input stream
+
+ @param backtraceDepth a sal_uInt32 value indicating the maximum backtrace
+ depth; zero means no backtrace
+
+ See @ref sal_log "basic logging functionality" for details.
+*/
+#define SAL_DEBUG_BACKTRACE(stream, backtraceDepth) \
+ do { \
+ if (sizeof ::sal::detail::getResult( \
+ ::sal::detail::StreamStart() << stream) == 1) \
+ { \
+ ::sal_detail_log( \
+ ::SAL_DETAIL_LOG_LEVEL_DEBUG, NULL, NULL, \
+ ::sal::detail::unwrapStream( \
+ ::sal::detail::StreamStart() << stream), \
+ backtraceDepth); \
+ } else { \
+ ::std::ostringstream sal_detail_stream; \
+ sal_detail_stream << stream; \
+ ::sal::detail::log( \
+ ::SAL_DETAIL_LOG_LEVEL_DEBUG, NULL, NULL, sal_detail_stream, \
+ backtraceDepth); \
+ } \
+ } while (false)
+
+
+
+#endif
+
+/* vim:set shiftwidth=4 softtabstop=4 expandtab: */