Logo Search packages:      
Sourcecode: virtualbox-ose version File versions  Download package

Assert - Assertions
[IPRT APIs]


Detailed Description

Assertions are generally used to check preconditions and other assumptions. Sometimes it is also used to catch odd errors or errors that one would like to inspect in the debugger. They should not be used for errors that happen frequently.

IPRT provides a host of assertion macros, so many that it can be a bit overwhelming at first. Don't despair, there is a system (surprise).

First there are four families of assertions:

Then there are variations wrt to argument list and behavior on failure:

In addition there is a very special family AssertCompile that can be used for some limited compile-time checking, like structure sizes and member alignment. This family doesn't have the same variations.

Remarks:
As you might have noticed, the macros don't follow the coding guidelines wrt to macros supposedly being all uppercase and underscored. For various reasons they don't, and nobody has complained yet. Wonder why... :-)

Each project has its own specific guidelines on how to use assertions, so the above is just trying to give you the general idea from the IPRT point of view.


Compile time assertions.

These assertions are used to check structure sizes, member/size alignments and similar compile time expressions.

int RTASSERTVAR [1]
typedef int RTASSERTTYPE [1]
#define AssertCompile(expr)   typedef int RTASSERTTYPE[(expr) ? 1 : 0]
#define AssertCompile2MemberOffsets(type, member1, member2)   AssertCompile(RT_OFFSETOF(type, member1) == RT_OFFSETOF(type, member2))
#define AssertCompileAdjacentMembers(type, member1, member2)   AssertCompile(RT_OFFSETOF(type, member1) + RT_SIZEOFMEMB(type, member1) == RT_OFFSETOF(type, member2))
#define AssertCompileMemberAlignment(type, member, align)   AssertCompile(!(RT_OFFSETOF(type, member) & ((align) - 1)))
#define AssertCompileMemberOffset(type, member, off)   AssertCompile(RT_OFFSETOF(type, member) == (off))
#define AssertCompileMemberSize(type, member, size)   AssertCompile(RT_SIZEOFMEMB(type, member) == (size))
#define AssertCompileMemberSizeAlignment(type, member, align)   AssertCompile(!(RT_SIZEOFMEMB(type, member) & ((align) - 1)))
#define AssertCompileSize(type, size)   AssertCompile(sizeof(type) == (size))
#define AssertCompileSizeAlignment(type, align)   AssertCompile(!(sizeof(type) & ((align) - 1)))

Implicit Test Handle API Variation

The test handle is retrieved from the test TLS entry of the calling thread.

va_list va

Globals for crash analysis

Remarks:
This is the full potential set, it


 RTDATADECL (uint32_t volatile) g_u32RTAssertLine
 RTDATADECL (const char *volatile) g_pszRTAssertExpr
 RTDATADECL (char) g_szRTAssertMsg1[1024]
 RTDECL (bool) RTAssertShouldPanic(void)

Release Logging

RT_C_DECLS_BEGIN RTDECL (void) RTAssertMsg1(const char *pszExpr

Assertions

These assertions will only trigger when RT_STRICT is defined. When it is undefined they will all be no-ops and generate no code.

#define Assert(expr)   do { } while (0)
#define AssertBreak(expr)
#define AssertBreakpoint()   do { } while (0)
#define AssertBreakStmt(expr, stmt)
#define AssertFailed()   do { } while (0)
#define AssertFailedBreak()
#define AssertFailedBreakStmt(stmt)
#define AssertFailedReturn(rc)
#define AssertFailedReturnStmt(stmt, rc)
#define AssertFailedReturnVoid()
#define AssertFailedReturnVoidStmt(stmt)
#define AssertMsg(expr, a)   do { } while (0)
#define AssertMsgBreak(expr, a)
#define AssertMsgBreakStmt(expr, a, stmt)
#define AssertMsgFailed(a)   do { } while (0)
#define AssertMsgFailedBreak(a)
#define AssertMsgFailedBreakStmt(a, stmt)
#define AssertMsgFailedReturn(a, rc)
#define AssertMsgFailedReturnVoid(a)
#define AssertMsgReturn(expr, a, rc)
#define AssertMsgReturnStmt(expr, a, stmt, rc)
#define AssertMsgReturnVoid(expr, a)
#define AssertMsgReturnVoidStmt(expr, a, stmt)
#define AssertMsgStmt(expr, a, stmt)
#define AssertReturn(expr, rc)
#define AssertReturnStmt(expr, stmt, rc)
#define AssertReturnVoid(expr)
#define AssertReturnVoidStmt(expr, stmt)
#define AssertStmt(expr, stmt)
#define RTAssertDoPanic()   RTAssertDebugBreak()
#define RTAssertPanic()   do { } while (0)

Fatal Assertions

These are similar to release assertions except that you cannot ignore them in any way, they will loop for ever if RTAssertDoPanic returns.

#define AssertFatal(expr)
#define AssertFatalFailed()
#define AssertFatalMsg(expr, a)
#define AssertFatalMsgFailed(a)

Convenience Assertions Macros

#define AssertFatalMsgRC(rc, msg)   AssertFatalMsg(RT_SUCCESS_NP(rc), msg)
#define AssertFatalRC(rc)   AssertFatalMsgRC(rc, ("%Rra\n", (rc)))
#define AssertFatalRCSuccess(rc)   AssertFatalMsg((rc) == VINF_SUCCESS, ("%Rra\n", (rc)))
#define AssertForEach(var, vartype, first, end, expr)
#define AssertGCPhys32(GCPhys)   AssertMsg(VALID_PHYS32(GCPhys), ("%RGp\n", (RTGCPHYS)(GCPhys)))
#define AssertGCPtr32(GCPtr)   AssertMsg(!((GCPtr) & UINT64_C(0xffffffff00000000)), ("%RGv\n", GCPtr))
#define AssertLogRelMsgRC(rc, msg)   AssertLogRelMsg(RT_SUCCESS_NP(rc), msg)
#define AssertLogRelMsgRCBreak(rc, msg)   AssertLogRelMsgBreak(RT_SUCCESS(rc), msg)
#define AssertLogRelMsgRCBreakStmt(rc, msg, stmt)   AssertLogRelMsgBreakStmt(RT_SUCCESS_NP(rc), msg, stmt)
#define AssertLogRelMsgRCReturn(rc, msg, rcRet)   AssertLogRelMsgReturn(RT_SUCCESS_NP(rc), msg, rcRet)
#define AssertLogRelMsgRCReturnVoid(rc, msg)   AssertLogRelMsgReturnVoid(RT_SUCCESS_NP(rc), msg)
#define AssertLogRelRC(rc)   AssertLogRelMsgRC(rc, ("%Rra\n", (rc)))
#define AssertLogRelRCBreak(rc)   AssertLogRelMsgRCBreak(rc, ("%Rra\n", (rc)))
#define AssertLogRelRCBreakStmt(rc, stmt)   AssertLogRelMsgRCBreakStmt(rc, ("%Rra\n", (rc)), stmt)
#define AssertLogRelRCReturn(rc, rcRet)   AssertLogRelMsgRCReturn(rc, ("%Rra\n", (rc)), rcRet)
#define AssertLogRelRCReturnVoid(rc)   AssertLogRelMsgRCReturnVoid(rc, ("%Rra\n", (rc)))
#define AssertLogRelRCSuccess(rc)   AssertLogRelMsg((rc) == VINF_SUCCESS, ("%Rra\n", (rc)))
#define AssertLogRelRCSuccessBreak(rc)   AssertLogRelMsgBreak((rc) == VINF_SUCCESS, ("%Rra\n", (rc)))
#define AssertLogRelRCSuccessBreakStmt(rc, stmt)   AssertLogRelMsgBreakStmt((rc) == VINF_SUCCESS, ("%Rra\n", (rc)), stmt)
#define AssertLogRelRCSuccessReturn(rc, rcRet)   AssertLogRelMsgReturn((rc) == VINF_SUCCESS, ("%Rra\n", (rc)), rcRet)
#define AssertLogRelRCSuccessReturnVoid(rc)   AssertLogRelMsgReturnVoid((rc) == VINF_SUCCESS, ("%Rra\n", (rc)))
#define AssertMsgRC(rc, msg)   do { AssertMsg(RT_SUCCESS_NP(rc), msg); NOREF(rc); } while (0)
#define AssertMsgRCBreak(rc, msg)   if (1) { AssertMsgBreak(RT_SUCCESS(rc), msg); NOREF(rc); } else do {} while (0)
#define AssertMsgRCBreakStmt(rc, msg, stmt)   if (1) { AssertMsgBreakStmt(RT_SUCCESS_NP(rc), msg, stmt); NOREF(rc); } else do {} while (0)
#define AssertMsgRCReturn(rc, msg, rcRet)   do { AssertMsgReturn(RT_SUCCESS_NP(rc), msg, rcRet); NOREF(rc); } while (0)
#define AssertMsgRCReturnVoid(rc, msg)   do { AssertMsgReturnVoid(RT_SUCCESS_NP(rc), msg); NOREF(rc); } while (0)
#define AssertPtr(pv)   AssertMsg(VALID_PTR(pv), ("%p\n", (pv)))
#define AssertPtrBreak(pv)   AssertMsgBreak(VALID_PTR(pv), ("%p\n", (pv)))
#define AssertPtrBreakStmt(pv, stmt)   AssertMsgBreakStmt(VALID_PTR(pv), ("%p\n", (pv)), stmt)
#define AssertPtrNull(pv)   AssertMsg(VALID_PTR(pv) || (pv) == NULL, ("%p\n", (pv)))
#define AssertPtrNullBreak(pv)   AssertMsgBreak(VALID_PTR(pv) || (pv) == NULL, ("%p\n", (pv)))
#define AssertPtrNullBreakStmt(pv, stmt)   AssertMsgBreakStmt(VALID_PTR(pv) || (pv) == NULL, ("%p\n", (pv)), stmt)
#define AssertPtrNullReturn(pv, rcRet)   AssertMsgReturn(VALID_PTR(pv) || (pv) == NULL, ("%p\n", (pv)), rcRet)
#define AssertPtrNullReturnVoid(pv)   AssertMsgReturnVoid(VALID_PTR(pv) || (pv) == NULL, ("%p\n", (pv)))
#define AssertPtrReturn(pv, rcRet)   AssertMsgReturn(VALID_PTR(pv), ("%p\n", (pv)), rcRet)
#define AssertPtrReturnVoid(pv)   AssertMsgReturnVoid(VALID_PTR(pv), ("%p\n", (pv)))
#define AssertRC(rc)   AssertMsgRC(rc, ("%Rra\n", (rc)))
#define AssertRCBreak(rc)   AssertMsgRCBreak(rc, ("%Rra\n", (rc)))
#define AssertRCBreakStmt(rc, stmt)   AssertMsgRCBreakStmt(rc, ("%Rra\n", (rc)), stmt)
#define AssertRCReturn(rc, rcRet)   AssertMsgRCReturn(rc, ("%Rra\n", (rc)), rcRet)
#define AssertRCReturnVoid(rc)   AssertMsgRCReturnVoid(rc, ("%Rra\n", (rc)))
#define AssertRCSuccess(rc)   AssertMsg((rc) == VINF_SUCCESS, ("%Rra\n", (rc)))
#define AssertRCSuccessBreak(rc)   AssertMsgBreak((rc) == VINF_SUCCESS, ("%Rra\n", (rc)))
#define AssertRCSuccessBreakStmt(rc, stmt)   AssertMsgBreakStmt((rc) == VINF_SUCCESS, ("%Rra\n", (rc)), stmt)
#define AssertRCSuccessReturn(rc, rcRet)   AssertMsgReturn((rc) == VINF_SUCCESS, ("%Rra\n", (rc)), rcRet)
#define AssertRCSuccessReturnVoid(rc)   AssertMsgReturnVoid((rc) == VINF_SUCCESS, ("%Rra\n", (rc)))
#define AssertReleaseMsgRC(rc, msg)   AssertReleaseMsg(RT_SUCCESS_NP(rc), msg)
#define AssertReleaseMsgRCBreak(rc, msg)   AssertReleaseMsgBreak(RT_SUCCESS(rc), msg)
#define AssertReleaseMsgRCBreakStmt(rc, msg, stmt)   AssertReleaseMsgBreakStmt(RT_SUCCESS_NP(rc), msg, stmt)
#define AssertReleaseMsgRCReturn(rc, msg, rcRet)   AssertReleaseMsgReturn(RT_SUCCESS_NP(rc), msg, rcRet)
#define AssertReleaseMsgRCReturnVoid(rc, msg)   AssertReleaseMsgReturnVoid(RT_SUCCESS_NP(rc), msg)
#define AssertReleaseRC(rc)   AssertReleaseMsgRC(rc, ("%Rra\n", (rc)))
#define AssertReleaseRCBreak(rc)   AssertReleaseMsgRCBreak(rc, ("%Rra\n", (rc)))
#define AssertReleaseRCBreakStmt(rc, stmt)   AssertReleaseMsgRCBreakStmt(rc, ("%Rra\n", (rc)), stmt)
#define AssertReleaseRCReturn(rc, rcRet)   AssertReleaseMsgRCReturn(rc, ("%Rra\n", (rc)), rcRet)
#define AssertReleaseRCReturnVoid(rc)   AssertReleaseMsgRCReturnVoid(rc, ("%Rra\n", (rc)))
#define AssertReleaseRCSuccess(rc)   AssertReleaseMsg((rc) == VINF_SUCCESS, ("%Rra\n", (rc)))
#define AssertReleaseRCSuccessBreak(rc)   AssertReleaseMsgBreak((rc) == VINF_SUCCESS, ("%Rra\n", (rc)))
#define AssertReleaseRCSuccessBreakStmt(rc, stmt)   AssertReleaseMsgBreakStmt((rc) == VINF_SUCCESS, ("%Rra\n", (rc)), stmt)
#define AssertReleaseRCSuccessReturn(rc, rcRet)   AssertReleaseMsgReturn((rc) == VINF_SUCCESS, ("%Rra\n", (rc)), rcRet)
#define AssertReleaseRCSuccessReturnVoid(rc)   AssertReleaseMsgReturnVoid((rc) == VINF_SUCCESS, ("%Rra\n", (rc)))

Release Log Assertions

These assertions will work like normal strict assertion when RT_STRICT is defined and LogRel statements when RT_STRICT is undefined. Typically used for things which shouldn't go wrong, but when it does you'd like to know one way or the other.

#define AssertLogRel(expr)
#define AssertLogRelBreak(expr)
#define AssertLogRelBreakStmt(expr, stmt)
#define AssertLogRelFailed()
#define AssertLogRelFailedBreak()
#define AssertLogRelFailedBreakStmt(stmt)
#define AssertLogRelFailedReturn(rc)
#define AssertLogRelFailedReturnVoid()
#define AssertLogRelMsg(expr, a)
#define AssertLogRelMsgBreak(expr, a)
#define AssertLogRelMsgBreakStmt(expr, a, stmt)
#define AssertLogRelMsgFailed(a)
#define AssertLogRelMsgFailedBreak(a)
#define AssertLogRelMsgFailedBreakStmt(a, stmt)
#define AssertLogRelMsgFailedReturn(a, rc)
#define AssertLogRelMsgFailedReturnVoid(a)
#define AssertLogRelMsgReturn(expr, a, rc)
#define AssertLogRelMsgReturnVoid(expr, a)
#define AssertLogRelReturn(expr, rc)
#define AssertLogRelReturnVoid(expr)
#define RTAssertLogRelMsg1(pszExpr, iLine, pszFile, pszFunction)
#define RTAssertLogRelMsg2(a)   LogRel(a)

Release Assertions

These assertions are always enabled.

#define AssertRelease(expr)
#define AssertReleaseBreak(expr)
#define AssertReleaseBreakStmt(expr, stmt)
#define AssertReleaseFailed()
#define AssertReleaseFailedBreak()
#define AssertReleaseFailedBreakStmt(stmt)
#define AssertReleaseFailedReturn(rc)
#define AssertReleaseFailedReturnVoid()
#define AssertReleaseMsg(expr, a)
#define AssertReleaseMsgBreak(expr, a)
#define AssertReleaseMsgBreakStmt(expr, a, stmt)
#define AssertReleaseMsgFailed(a)
#define AssertReleaseMsgFailedBreak(a)
#define AssertReleaseMsgFailedBreakStmt(a, stmt)
#define AssertReleaseMsgFailedReturn(a, rc)
#define AssertReleaseMsgFailedReturnVoid(a)
#define AssertReleaseMsgReturn(expr, a, rc)
#define AssertReleaseMsgReturnVoid(expr, a)
#define AssertReleaseReturn(expr, rc)
#define AssertReleaseReturnVoid(expr)
#define RTAssertReleasePanic()   do { RTAssertShouldPanic(); RTAssertDoPanic(); } while (0)

Defines

#define RTAssertDebugBreak()   do { RT_BREAKPOINT(); } while (0)

Variables

RT_C_DECLS_BEGIN unsigned
const char * 
pszFile
RT_C_DECLS_BEGIN unsigned
const char const char * 
pszFunction
RT_C_DECLS_BEGIN unsigned uLine


Generated by  Doxygen 1.6.0   Back to index