Assertions and panics

To help Symbian developers identify potential problems early in development, macros are provided to test for error conditions in functions (asserts) and objects (class invariants). Assertions are implemented using panics.

Testing conditions with asserts and invariants

One method of catching errors early is to identify conditions that should be true at the beginning and end of functions, and raise errors if they are not.

Two mechanisms support this programming style.

  • asserts

  • class invariants

Assertions

Two macros are supplied for asserting specific conditions in functions:

  • __ASSERT_ALWAYS to catch run-time invalid input, for both release and debug builds

  • __ASSERT_DEBUG to catch programming errors, for debug builds only

Class Invariants

Class invariants are used to test that an object is in a valid state. They are used only in debug builds.

  • Define class invariants for non-trivial classes using __DECLARE_TEST. The class must supply functions that specify its allowed stable states.

  • To ensures that the object is in a stable state prior to executing the function, call the invariant at the start of all public functions using __TEST_INVARIANT.

  • For non-const functions, you can ensure that the object has been left in a stable state by also calling the invariant at the end of the function.

Panics

Some types of error are due to bad program code, such as passing an illegal parameter value. When this type of error is discovered, the thread associated with the erroneous program should be terminated. On the Symbian platform, this is a referred to as a panic. The only proper response to a panic is to fix the program code.

Typically, a panic is not discovered by the program that made the error, but by some library code which operates on behalf of that program. If the library code is in a DLL running in the same thread as the program, it calls User::Panic() to panic the thread. If the library code is in a server executing on behalf of another program, the server panics the client thread by calling RMessagePtr2::Panic(), where RMessagePtr2 is the handle to the message sent by the client to the server.

Panics are characterized by two pieces of information:

  • category - a string of up to sixteen characters, which defines the context of a panic.

  • panic number - a number that, in the context of a category, identifies the specific cause of the panic.

Typical panic values you may encounter as a Symbian developer include:
  • KERN-EXEC 3 — raised by an unhandled exception such as an access violation caused, for example, by dereferencing NULL or an invalid pointer.

  • E32USER-CBASE 46 — raised by the active scheduler as a result of a stray signal. This could occur if you have forgotten to call an active object's SetActive() method after making an asynchronous request.

  • USER 11 — raised when an operation to modify a descriptor fails because the operation would cause the descriptor to exceed its maximum allocated length.

Related concepts