[webkit-dev] How to use ASSERT_NO_EXCEPTION

[Darin Adler]

Here’s my first draft of a note about ASSERT_NO_EXCEPTION. We might want to add this to the WebCore website; not sure.

Many core DOM functions in classes in WebCore serve a dual purpose.

They are used to implement DOM API that can be called from JavaScript. This often means that they will handle exceptional cases by raising a DOM exception. For example, if you call appendChild and pass a null pointer for the child, you will get a NOT_FOUND_ERR exception.

Those same functions are often used to implement the internals of the web engine. In those cases, they are called by callers who can guarantee none of the exceptional cases exist. Before ASSERT_NO_EXCEPTION, here’s how you would write a call like that:

    ExceptionCode ec;
    appendChild(newChild, ec);
    ASSERT(!ec);

That’s pretty ugly, and we can do better. ASSERT_NO_EXCEPTION lets us do these two things:

    #include "ExceptionCodePlaceholder.h"

    appendChild(newChild, ASSERT_NO_EXCEPTION);

That’s pretty good, but this is even better:

    appendChild(newChild);

To allow the last style, we add the ExceptionCodePlaceholder.h include to the header file and make ASSERT_NO_EXCEPTION the default argument for the ExceptionCode& in the function’s declaration in the header. If you look at ContainerNode.h you can see that in use for appendChild.

Here are some rules of thumb for using this:

    1) If there’s a DOM function where callers inside WebCore can easily guarantee that no exception will be raised, it’s recommended to add ASSERT_NO_EXCEPTION as a default value for the ExceptionCode& argument.

    2) If you need to call a function like this, first double check that you can indeed guarantee that no exception will occur, then either use ASSERT_NO_EXCEPTION directly and 

    3) Do not use ASSERT_NO_EXCEPTION if the exception is possible. Be sure that you know why there is no exception possible before using this technique. In some cases, you may even need to add a comment to the source code explaining why no exception is possible.

-- Darin