GL Studio C++ Runtime API
disti_assert.h
Go to the documentation of this file.
1/// \file disti_assert.h
2/// \brief Contains the DistiAssert macro.
3///
4/// \par Copyright Information
5///
6/// Copyright (c) 2017 by The DiSTI Corporation.<br>
7/// 12249 Science Drive; Suite 300<br>
8/// Orlando, Florida 32826<br>
9/// USA<br>
10/// <br>
11/// All rights reserved.<br>
12///
13/// This Software contains proprietary trade secrets of DiSTI and may not be
14/// reproduced, in whole or part, in any form, or by any means of electronic,
15/// mechanical, or otherwise, without the written permission of DiSTI. Said
16/// permission may be derived through the purchase of applicable DiSTI product
17/// licenses which detail the distribution rights of this content and any
18/// Derivative Works based on this or other copyrighted DiSTI Software.
19///
20/// NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
21/// AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
22/// PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
23/// AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
24/// IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
25/// PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
26///
27/// LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
28/// IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
29/// INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
30/// DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
31/// INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
32/// INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
33/// OF SUCH DAMAGES. DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
34/// EXCEED FIVE DOLLARS (US$5.00).
35///
36/// The aforementioned terms and restrictions are governed by the laws of the
37/// State of Florida and the United States of America.
38
39#ifndef INCLUDED_DISTI_ASSERT_H
40#define INCLUDED_DISTI_ASSERT_H
41
42#include "disti_include.h"
44#include <stddef.h>
45
46namespace disti
47{
48class DistiException;
49
50/// Swaps the incoming DistiException objects.
51/// \param first The first object to swap.
52/// \param second The other object to swap.
53DISTI_EXPORT void swap( DistiException& first, DistiException& second ) DISTI_FUNC_NOEXCEPT;
54
55/** DistiException just contains a string error message */
57{
58public:
59 /// Construct a DistiException with the given error message.
60 /// \param what The error message.
61 explicit DISTI_EXPORT DistiException( const char* what );
62
63 /// Copy constructor
64 /// \param other The object to copy.
65 DISTI_EXPORT DistiException( const DistiException& other );
66
67 /// Assignment operator
68 /// \param other The object value to assign.
69 /// \return The new object.
70 DISTI_EXPORT DistiException& operator=( DistiException other );
71
72#ifdef DISTI_HAS_RVAL_REFS
73 /// Move operator
74 /// \param other The object to move.
76#endif
77 virtual DISTI_EXPORT ~DistiException();
78
79 /// \note Never returns NULL.
80 /// \return The underlying error string.
81 virtual DISTI_EXPORT const char* what() const;
82
83 friend DISTI_EXPORT void swap( DistiException& first, DistiException& second ) DISTI_FUNC_NOEXCEPT;
84
85private:
86 char* _what; ///< The error string.
87 size_t _len; ///< The length of the error string.
88};
89
90/** The callback type. It receives an error message string */
91typedef void ( *DistiAssertHandler )( const char* errMessage );
92
93/// This function enables users to override the default behavior of DistiAssert(), which is used
94/// throughout the GL Studio code base to test prerequisites etc. The user can set a function to
95/// be called when DistiAssert fires. Only one callback can be registered, so calling the set
96/// function multiple times overwrites the previous handler. If the given handler is null,
97/// DistiAssert() reverts to its default behavior.
98/// \note This function is deprecated; Use SetGlsVerifyHandler or SetGlsAssertHandler instead.
100
101/// This function enables users to override the default behavior of GLS_VERIFY(), which is used
102/// throughout the GL Studio code base to test prerequisites etc. The user can set a function to
103/// be called when GLS_VERIFY fires. Only one callback can be registered, so calling the set
104/// function multiple times overwrites the previous handler. If the given handler is null,
105/// GLS_VERIFY() reverts to its default behavior.
107
108/// This function enables users to override the default behavior of GLS_ASSERT(), which is used
109/// throughout the GL Studio code base to test prerequisites etc. The user can set a function to
110/// be called when GLS_ASSERT fires. Only one callback can be registered, so calling the set
111/// function multiple times overwrites the previous handler. If the given handler is null,
112/// GLS_ASSERT() reverts to its default behavior.
114
115/// If a callback is registered, that function is invoked when an assertion fails (exp is false).
116/// If the callback is null, when the assertion fails, DistiAssert will popup a messagebox allowing
117/// the user to Abort, Retry(Debug) or Ignore the error. Retry will cause a User breakpoint on the
118/// error, Abort will throw a DistiException describing the error, and Ignore does nothing.
119/// At present, the function does the same thing in debug and release modes.
120/// \note This function is deprecated; Use GLS_ASSERT or GLS_VERIFY instead.
121#if defined( GLS_DEBUG )
122# define DistiAssert( exp ) (void)( ( exp ) || ( ::disti::DistiAssertDebug( # exp, __FILE__, __LINE__ ), 0 ) )
123#else
124# define DistiAssert( exp ) (void)( ( exp ) || ( ::disti::DistiAssertRelease( # exp, __FILE__, __LINE__ ), 0 ) )
125#endif
126
127/// Convenience macro to quiet warnings about unused return values.
128#define GLS_UNUSED( exp ) \
129 do \
130 { \
131 (void)sizeof( exp ); \
132 } while( 0 )
133
134/** In builds where GLS_DEBUG is defined OR where NDEBUG is not defined, this macro has the following behavior:
135 *
136 * 1. If a callback is registered with SetGlsAssertHandler(), that handler is invoked when an assertion
137 * fails (\a exp is false).
138 *
139 * 2. If no handler is registered and the assertion fails, on Windows GLS_ASSERT will popup a message box
140 * allowing the user to Abort, Retry (Debug), or Ignore the error. Retry will cause a User breakpoint
141 * on the error, Abort will throw a DistiException describing the error, and Ignore does nothing.
142 *
143 * If none of the aforementioned symbols are defined, this function does nothing, and does not evaluate \a exp.
144 *
145 * \note Use this function instead of the deprecated DistiAssert() macro for checks that should be tested in
146 * Debug builds only.
147 */
148#if defined( GLS_DEBUG ) || !defined( NDEBUG )
149# define GLS_ASSERT( exp ) \
150 do \
151 { \
152 (void)( ( exp ) || ( ::disti::GlsAssert( #exp, __FILE__, __LINE__ ), 0 ) ); \
153 } while( 0 )
154#else
155# define GLS_ASSERT( exp ) GLS_UNUSED( exp )
156#endif
157
158/** The GLS_VERIFY() macro has the following behavior:
159 *
160 * 1. If a callback is registered with SetGlsVerifyHandler(), that handler is invoked when \a exp is false.
161 *
162 * 2. If no handler is registered and the \a exp is false, on Windows GLS_VERIFY() will popup a message box
163 * allowing the user to Abort, Retry (Debug), or Ignore the error. Retry will cause a User breakpoint
164 * on the error, Abort will throw a DistiException describing the error, and Ignore does nothing.
165 *
166 * \note Use this function instead of the deprecated DistiAssert() macro for checks that should be tested in
167 * both Debug and Release builds.
168 */
169#define GLS_VERIFY( exp ) (void)( ( exp ) || ( ::disti::GlsVerify( #exp, __FILE__, __LINE__ ), 0 ) )
170
171/// Do not call DistiAssertDebug directly, instead use the DistiAssert macro
172/// \note This function is deprecated; Use GlsAssert or GlsVerify instead.
173/// \param expression The string representation of the code being asserted.
174/// \param filename The file where the code resides.
175/// \param lineNumber The line number where the code resides.
176DISTI_EXPORT void DistiAssertDebug( const char* expression, const char* filename, unsigned int lineNumber );
177
178/// Do not call DistiAssertRelease directly, instead use the DistiAssert macro
179/// \note This function is deprecated; Use GlsAssert or GlsVerify instead.
180/// \param expression The string representation of the code being asserted.
181/// \param filename The file where the code resides.
182/// \param lineNumber The line number where the code resides.
183DISTI_EXPORT void DistiAssertRelease( const char* expression, const char* filename, unsigned int lineNumber );
184
185/// Do not call GlsVerify directly, instead use the GLS_VERIFY macro.
186/// \param expression The string representation of the code being asserted.
187/// \param filename The file where the code resides.
188/// \param lineNumber The line number where the code resides.
189DISTI_EXPORT void GlsVerify( const char* expression, const char* filename, unsigned int lineNumber );
190
191/// Do not call GlsAssert directly, instead use the GLS_ASSERT macro.
192/// \param expression The string representation of the code being asserted.
193/// \param filename The file where the code resides.
194/// \param lineNumber The line number where the code resides.
195DISTI_EXPORT void GlsAssert( const char* expression, const char* filename, unsigned int lineNumber );
196
197/// Assert the pointer is not null and return it.
198/// \param p The pointer to check.
199/// \return The pointer that was checked.
200template<class T>
201T* ValidatePointer( const T* const p )
202{
203 DistiAssert( p );
204 return p;
205}
206
207} // namespace disti
208
209#endif
Definition: disti_assert.h:57
virtual const char * what() const
DistiException & operator=(DistiException other)
friend void swap(DistiException &first, DistiException &second)
DistiException(const char *what)
#define DistiAssert(exp)
Definition: disti_assert.h:124
A file for all GL Studio files to include.
Macros and helper code to determine what subset of C++11/14/17 is available.
#define DISTI_FUNC_NOEXCEPT
Macro to wrap the noexcept keyword, removed on compilers that don't support it.
Definition: gls_cpp_lang_support.h:239
Definition: bmpimage.h:46
void GlsAssert(const char *expression, const char *filename, unsigned int lineNumber)
void(* DistiAssertHandler)(const char *errMessage)
Definition: disti_assert.h:91
void DistiAssertRelease(const char *expression, const char *filename, unsigned int lineNumber)
void GlsVerify(const char *expression, const char *filename, unsigned int lineNumber)
T * ValidatePointer(const T *const p)
Definition: disti_assert.h:201
void SetGlsAssertHandler(DistiAssertHandler)
void DistiAssertDebug(const char *expression, const char *filename, unsigned int lineNumber)
void swap(DistiException &first, DistiException &second)
void SetGlsVerifyHandler(DistiAssertHandler)
void SetDistiAssertHandler(DistiAssertHandler)