include/osl/diagnose.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20
  21 #ifndef _OSL_DIAGNOSE_H_
  22 #define _OSL_DIAGNOSE_H_
  23
  24 #include "sal/config.h"
  25
  26 #include "sal/detail/log.h"
  27 #include "sal/saldllapi.h"
  28 #include "sal/types.h"
  29
  30 /** provides simple diagnostic support
  31
  32     The facilities provided by this header are deprecated.  True assertions
  33     (that detect broken program logic) should use standard assert (which aborts
  34     if an assertion fails, and is controlled by the standard NDEBUG macro).
  35     Logging of warnings (e.g., about malformed input) and traces (e.g., about
  36     steps taken while executing some protocol) should use the facilities
  37     provided by (C++ only) sal/log.hxx.
  38
  39     Because the assertion macros (OSL_ASSERT, OSL_ENSURE, OSL_FAIL, OSL_PRECOND,
  40     and OSL_POSTCOND) have been used for true assertions as well as for logged
  41     warnings, they map to SAL_WARN instead of standard assert.  OSL_TRACE maps
  42     to SAL_INFO.
  43
  44     The functions defined in this header are not intended to be used directly,
  45     but through defined macros. The macros can be divided into three categories:
  46     assertions, traces and other stuff .-) Their usability depends on the value
  47     of OSL_DEBUG_LEVEL macro: assertions are only active if OSL_DEBUG_LEVEL is 1
  48     or greater, traces if OSL_DEBUG_LEVEL is 2 or greater.
  49
  50     Assertions (cond is bool, msg is char*):
  51     OSL_ASSERT(cond)
  52         If cond is false, reports an error.
  53
  54     OSL_ENSURE(cond, msg)
  55         If cond is false, reports an error with message msg.
  56
  57     OSL_FAIL(msg)
  58         Reports an error with message msg unconditionally.
  59
  60     OSL_PRECOND(cond, msg)
  61     OSL_POSTCOND(cond, msg)
  62         These two are functionally equivalent to OSL_ENSURE(cond, msg). They are
  63         intended to be used for checking pre- and postconditions of functions.
  64
  65     Traces:
  66     OSL_TRACE(fmt, args...)
  67         Prints trace message. The arguments have the same meaning as the
  68         arguments of printf.
  69
  70     Other:
  71     OSL_VERIFY(expr)
  72         Evaluates the expression and if it is false, reports an error. The
  73         expression is evaluated once without regard of the value of
  74         OSL_DEBUG_LEVEL.
  75
  76         Example:
  77
  78         void extractBool(Any const& rAny, bool& rBool)
  79         {
  80             OSL_VERIFY(rAny >>= rBool);
  81         }
  82
  83     OSL_DEBUG_ONLY(expr)
  84  */
  85
  86 #if !defined OSL_DEBUG_LEVEL
  87 #define OSL_DEBUG_LEVEL 0
  88 #endif
  89
  90 #ifdef __cplusplus
  91 extern "C" {
  92 #endif  /* __cplusplus */
  93
  94 /* //////////////////////////////////////////////////////////////////////////
  95     Diagnostic support
  96 */
  97
  98 SAL_DLLPUBLIC void        SAL_CALL osl_breakDebug(void);
  99 SAL_DLLPUBLIC sal_Bool    SAL_CALL osl_assertFailedLine(const sal_Char* pszFileName, sal_Int32 nLine, const sal_Char* pszMessage);
 100 SAL_DLLPUBLIC void        SAL_CALL osl_trace(const sal_Char* pszFormat, ...);
 101 SAL_DLLPUBLIC sal_Int32   SAL_CALL osl_reportError(sal_uInt32 nType, const sal_Char* pszErrorMessage);
 102
 103 /*
 104     For message delivery
 105 */
 106
 107 /** a message delivery function which receives a pre-formatted message string
 108 */
 109 typedef void (SAL_CALL *pfunc_osl_printDebugMessage)( const sal_Char * pszMessage );
 110
 111 /** a message delivery function which receives detailed information about where the message was triggered
 112 */
 113 typedef void (SAL_CALL *pfunc_osl_printDetailedDebugMessage)( const sal_Char * pszFileName, sal_Int32 nLine, const sal_Char* pszMessage );
 114
 115 /** sets a message delivery function
 116
 117     The function set here is ignored if a function for detailed message information
 118     (pfunc_osl_printDetailedDebugMessage) has been set.
 119
 120     The given message handler must be able to cope with a null message.
 121 */
 122 SAL_DLLPUBLIC pfunc_osl_printDebugMessage SAL_CALL osl_setDebugMessageFunc( pfunc_osl_printDebugMessage pNewFunc );
 123
 124 /** sets a delivery function for detailed message information.
 125
 126     The given message handler must be able to cope with a null message.
 127 */
 128 SAL_DLLPUBLIC pfunc_osl_printDetailedDebugMessage SAL_CALL osl_setDetailedDebugMessageFunc( pfunc_osl_printDetailedDebugMessage pNewFunc );
 129
 130 #ifdef __cplusplus
 131 }
 132 #endif
 133
 134 #define OSL_THIS_FILE       __FILE__
 135
 136 /* the macro OSL_LOG_PREFIX is intended to be an office internal macro for now
 137
 138    it is deprecated and superseded by (C++ only) SAL_WHERE
 139 */
 140 #define OSL_LOG_PREFIX SAL_DETAIL_WHERE
 141
 142 #define OSL_DEBUG_ONLY(s)   _OSL_DEBUG_ONLY(s)
 143
 144 #define OSL_TRACE(...) \
 145     SAL_DETAIL_INFO_IF_FORMAT(OSL_DEBUG_LEVEL > 0, "legacy.osl", __VA_ARGS__)
 146
 147 #if OSL_DEBUG_LEVEL > 0
 148 #define OSL_ASSERT(c) \
 149     SAL_DETAIL_WARN_IF_FORMAT(!(c), "legacy.osl", "OSL_ASSERT: %s", #c)
 150 #define OSL_ENSURE(c, m) SAL_DETAIL_WARN_IF_FORMAT(!(c), "legacy.osl", "%s", m)
 151 #define OSL_FAIL(m) SAL_DETAIL_WARN_IF_FORMAT(sal_True, "legacy.osl", "%s", m)
 152 #else
 153 #define OSL_ASSERT(c) ((void) 0)
 154 #define OSL_ENSURE(c, m) ((void) 0)
 155 #define OSL_FAIL(m) ((void) 0)
 156 #endif
 157
 158 #define OSL_VERIFY(c) do { if (!(c)) OSL_ASSERT(0); } while (0)
 159 #define OSL_PRECOND(c, m)   OSL_ENSURE(c, m)
 160 #define OSL_POSTCOND(c, m)  OSL_ENSURE(c, m)
 161
 162
 163 #ifdef __cplusplus
 164 #define _OSL_GLOBAL ::
 165 #else
 166 #define _OSL_GLOBAL
 167 #endif  /* __cplusplus */
 168
 169 #if OSL_DEBUG_LEVEL > 0
 170
 171 #define _OSL_DEBUG_ONLY(f)  (f)
 172
 173 #else
 174
 175 #define _OSL_DEBUG_ONLY(f)          ((void)0)
 176
 177 #endif /* OSL_DEBUG_LEVEL */
 178
 179 /* the macro OSL_THIS_FUNC is intended to be an office internal macro for now */
 180 /* copied from boost/current_function.hpp to make it usable from C
 181  * sources as well
 182  *
 183  * Copyright (c) 2002 Peter Dimov and Multi Media Ltd.
 184  *
 185  * Distributed under the Boost Software License, Version 1.0. (See
 186  * accompanying file LICENSE_1_0.txt or copy at
 187  * http://www.boost.org/LICENSE_1_0.txt) */
 188 #if defined(__GNUC__) || (defined(__MWERKS__) && (__MWERKS__ >= 0x3000)) || (defined(__ICC) && (__ICC >= 600))
 189 #define OSL_THIS_FUNC __PRETTY_FUNCTION__
 190 #elif defined(__DMC__) && (__DMC__ >= 0x810)
 191 #define OSL_THIS_FUNC __PRETTY_FUNCTION__
 192 #elif defined(__FUNCSIG__)
 193 #define OSL_THIS_FUNC __FUNCSIG__
 194 #elif (defined(__INTEL_COMPILER) && (__INTEL_COMPILER >= 600)) || (defined(__IBMCPP__) && (__IBMCPP__ >= 500))
 195 #define OSL_THIS_FUNC __FUNCTION__
 196 #elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901)
 197 #define OSL_THIS_FUNC __func__
 198 #else
 199 #define OSL_THIS_FUNC ""
 200 #endif
 201
 202 #endif /* _OSL_DIAGNOSE_H_ */
 203
 204 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */