#include <cafe/os/OSException.h>

#define OS_EXCEPTION_MODE_THREAD               1
#define OS_EXCEPTION_MODE_GLOBAL               2

typedef BOOL (*OSExceptionCallback)(OSContext* interruptedContext);

OSExceptionCallback OSSetExceptionCallbackEx(OSExceptionMode exceptionMode,
                                             OSExceptionType exceptionType,
                                             OSExceptionCallback newCallback);


exceptionMode Exception mode to set callback.
exceptionType Exception type to set callback.
newCallback Pointer to the new exception callback.

Return Values

The existing callback pointer.

NULL is returned if no previous handler was installed. NULL is a valid value to set the specific exception handler to "do nothing".


For more information about exception callback usage, see OSSetExceptionCallback.

OSSetExceptionCallbackEx has four extended exception setting modes:

  1. OS_EXCEPTION_MODE_THREAD - This behaves like the original OSSetExceptionCallback call. This sets an exception handler per-thread per-core.
  2. OS_EXCEPTION_MODE_GLOBAL - This allows a global per-core exception handler to be installed. If a thread has no defined exception handler, the global exception handler for the core is used.
  3. OS_EXCEPTION_MODE_THREAD_ALL_CORES - This sets the exception handler per-thread for all cores. A thread can migrate to another core and still can call the desired per-thread exception handler.
  4. OS_EXCEPTION_MODE_GLOBAL_ALL_CORES - This sets the global exception handler for all cores. A thread does not need to have a per-thread exception handler. This is useful for a thread which can migrate and is created without a per-thread exception handler.

OSSetExceptionCallbackEx allows global exception handlers to be set per-core that are different than the per-thread exception handlers.

Currently, the policy for the per-core exception handler priority lookup is:

  1. If thread exception handler exists, then use that.
  2. If thread exception handler does not exists, and if global exception handler exists, then use that.
  3. If thread exception handler does not exists, and if global exception handler does not exists, then perform system unhanded crash functionality.

This allows one to handle exceptions without having to inherit the exception handler from a default thread (this is useful for threads, which are in different libraries).

Do Not Call From

Callbacks Do not call this function from any callback function.

Revision History

2014/04/18 Initial version.