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 INCLUDED_OSL_DIAGNOSE_H
  22 #define INCLUDED_OSL_DIAGNOSE_H
  23
  24 #include "sal/config.h"
  25
  26 #include "sal/detail/log.h"
  27 #include "sal/types.h"
  28
  29 /** @file
  30     Provides simple diagnostic support.
  31
  32     @deprecated
  33     The facilities provided by this header are deprecated.  True assertions
  34     (that detect broken program logic) should use standard assert (which aborts
  35     if an assertion fails, and is controlled by the standard NDEBUG macro).
  36     Logging of warnings (e.g., about malformed input) and traces (e.g., about
  37     steps taken while executing some protocol) should use the facilities
  38     provided by (C++ only) sal/log.hxx.
  39
  40     Because the assertion macros (OSL_ASSERT, OSL_ENSURE, OSL_FAIL, OSL_PRECOND,
  41     and OSL_POSTCOND) have been used for true assertions as well as for logged
  42     warnings, they map to SAL_WARN instead of standard assert.  OSL_TRACE maps
  43     to SAL_INFO.
  44
  45     The functions defined in this header are not intended to be used directly,
  46     but through defined macros. The macros can be divided into three categories:
  47     assertions, traces and other stuff .-) Their usability depends on the value
  48     of OSL_DEBUG_LEVEL macro: assertions are only active if OSL_DEBUG_LEVEL is 1
  49     or greater, traces if OSL_DEBUG_LEVEL is 2 or greater.
  50
  51     Traces:
  52     OSL_TRACE(fmt, args...)
  53         Prints trace message. The arguments have the same meaning as the
  54         arguments of printf.
  55  */
  56
  57 #if !defined OSL_DEBUG_LEVEL
  58 #define OSL_DEBUG_LEVEL 0
  59 #endif
  60
  61 /** @internal The macro OSL_LOG_PREFIX is intended to be an office internal macro for now
  62     @deprecated superseded by (C++ only) SAL_WHERE
  63 */
  64 #define OSL_LOG_PREFIX SAL_DETAIL_WHERE
  65
  66 /** Prints trace message.
  67
  68     The arguments have the same meaning as the arguments of printf.
  69 */
  70 #define OSL_TRACE(...) \
  71     SAL_DETAIL_INFO_IF_FORMAT(OSL_DEBUG_LEVEL > 0, "legacy.osl", __VA_ARGS__)
  72
  73 /** @defgroup assert Assertions
  74
  75     Assertions (cond is bool, msg is char*).
  76
  77     @{
  78  */
  79
  80 /** If cond is false, reports an error. */
  81 #define OSL_ASSERT(c) \
  82     SAL_DETAIL_WARN_IF_FORMAT(!(c), "legacy.osl", "OSL_ASSERT: %s", #c)
  83 /** If cond is false, reports an error with message msg. */
  84 #define OSL_ENSURE(c, m) SAL_DETAIL_WARN_IF_FORMAT(!(c), "legacy.osl", "%s", m)
  85 /** Reports an error with message msg unconditionally. */
  86 #define OSL_FAIL(m) SAL_DETAIL_WARN_IF_FORMAT(sal_True, "legacy.osl", "%s", m)
  87
  88 /** Evaluates the expression and if it is false, reports an error. The
  89     expression is evaluated once without regard of the value of
  90     OSL_DEBUG_LEVEL.
  91
  92     Example:
  93
  94     @code{.c}
  95
  96     void extractBool(Any const& rAny, bool& rBool)
  97     {
  98         OSL_VERIFY(rAny >>= rBool);
  99     }
 100
 101     @endcode
 102 */
 103 #define OSL_VERIFY(c) do { if (!(c)) OSL_ASSERT(0); } while (0)
 104
 105 /** Check the precondition of functions.
 106
 107     Functionally equivalent to OSL_ENSURE(cond, msg).
 108 */
 109 #define OSL_PRECOND(c, m)   OSL_ENSURE(c, m)
 110
 111 /** Check the postcondition of functions.
 112
 113     Functionally equivalent to OSL_ENSURE(cond, msg).
 114 */
 115 #define OSL_POSTCOND(c, m)  OSL_ENSURE(c, m)
 116
 117 /** @} */
 118
 119 /* the macro OSL_THIS_FUNC is intended to be an office internal macro for now */
 120 /* copied from boost/current_function.hpp to make it usable from C
 121  * sources as well
 122  *
 123  * Copyright (c) 2002 Peter Dimov and Multi Media Ltd.
 124  *
 125  * Distributed under the Boost Software License, Version 1.0. (See
 126  * accompanying file LICENSE_1_0.txt or copy at
 127  * http://www.boost.org/LICENSE_1_0.txt) */
 128 #if defined(__GNUC__)
 129 #define OSL_THIS_FUNC __PRETTY_FUNCTION__
 130 #elif defined(__FUNCSIG__)
 131 #define OSL_THIS_FUNC __FUNCSIG__
 132 #elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901)
 133 #define OSL_THIS_FUNC __func__
 134 #else
 135 #define OSL_THIS_FUNC ""
 136 #endif
 137
 138 #endif // INCLUDED_OSL_DIAGNOSE_H
 139
 140 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */