The WebKit Open Source Project

A guide to Assertion macros in WebKit

Version 1, 2010-5-24


WebKit provides a number of macros to assert that conditions in the code are met. They are defined in Source/JavaScriptCore/wtf/Assertions.h. This document provides an overview of the various macros, including guidelines and best practices for their use.

Types of ASSERT macros

The ASSERT() macro and its variants are compiled out of release builds. They are meant for use during the development process to catch programming mistakes. For those macros that accept an expression as an argument, the expression is also compiled out of release builds and thus incurs no overhead in shipping code.

The CRASH() macro

CRASH() raises a fatal error resulting in program termination and triggering either the debugger or the crash reporter. It is active in both debug & release mode. CRASH() directly affects users in that it will disrupt or end their browsing session. If a browser vendor traces crashes, it can be extremely helpful in diagnosing hard to find issues that may only occur on users' machines.

Considerations when using ASSERT() and CRASH() macros.

Hazards of using the ASSERT() family of macros

The expression inside the ASSERT and ASSERT_UNUSED macro is compiled out of release builds together with the macro itself. If the expression that's used has side effects, its omission in release build can lead to programming errors that don't manifest in debug builds.

The benefits of using CRASH:

The cost of using CRASH:

Guidelines for using ASSERT() and CRASH() macros.

Examples of using CRASH() vs ASSERT()

// Not having any children indicates a programming error.
ASSERT(object->numChildren() > 0);

Allocation bitmapStorage = systemAlloc(allocSize);
if (!bitmapStorage.pages)
    CRASH(); // Not possible to recover from an out of memory error.

If you have any comments on the above or other ideas about improving the clarity, scope, or presentation, please send mail to the WebKit mailing list.