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/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
91extern "C" {
92#endif /* __cplusplus */
93
94/* //////////////////////////////////////////////////////////////////////////
95 Diagnostic support
96*/
97
98SAL_DLLPUBLIC void SAL_CALL osl_breakDebug(void);
99SAL_DLLPUBLIC sal_Bool SAL_CALL osl_assertFailedLine(const sal_Char* pszFileName, sal_Int32 nLine, const sal_Char* pszMessage);
100SAL_DLLPUBLIC void SAL_CALL osl_trace(const sal_Char* pszFormat, ...);
101SAL_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*/
109typedef 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*/
113typedef 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*/
122SAL_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*/
128SAL_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 // INCLUDED_OSL_DIAGNOSE_H
203
204/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
205