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
_______________________________________________
webkit-dev mailing list
webkit-dev@lists.webkit.org
http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
