__DECLARE_TEST

__DECLARE_TEST public: void __DbgTestInvariant() const; void __DbgTest(TAny *aPtr) const

Support

Supported from 5.0

Description

Declares a function for testing object invariance.

For complex classes, it is often useful to provide a function that can be called to check that the object is in a valid state. The __DECLARE_TEST macro supplies a standard prototype for such a function named __DbgTestInvariant(). A companion macro __TEST_INVARIANT is provided to call the function.

For DLLs, as opposed to EXEs, __DbgTestInvariant() is exported. That is, the macro expands to:

public: IMPORT_C void __DbgTestInvariant() const; void __DbgTest(TAny *aPtr) const

This macro should placed as the last item in a class declaration (as it switches back to public access). Note that a terminating semi-colon must be used.

You should define the __DbgTestInvariant() function to check that the object is in a healthy state. If it finds an error, it should call User::Invariant(), which will cause a panic.

If a class is derived from a base class, then the base class __DbgTestInvariant() should be called first, and then any further checking done.

The second function declared, __DbgTest(), is intended to allow test code a way of directly accessing non-public members of a class. The function is implemented by any test code that requires it, rather than in the class’s own source code. The function is therefore not exported.

__DECLARE_TEST is defined for both debug and release builds. This point is particularly important for DLLs, as otherwise the exported interfaces would differ between the build versions, giving potential binary compatibility problems. To avoid using memory unnecessarily in release builds, you can, however, use preprocessor directives to define the code within __DbgTestInvariant() only for debug builds. __DbgTestInvariant() is never called in release builds.

See also:

• Using __DECLARE_TEST