Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
Error Handling

Most Zen functions return a kStatus value to the caller, which can be used by the caller to detect errors. Common kStatus values include kOK (no error), kERROR (general error), and kERROR_PARAMETER (invalid parameter).

kStatus status;
status = kArrayList_Construct(&list, kTypeOf(k32s), 0, kNULL);
if (status == kOK)
{
//...
}
else if (status == kERROR_MEMORY)
{
//...
}

A variety of error-handling macros are provided to simplify the process of dealing with error codes. The most common error-handling macro is kCheck:

kStatus TestFunction()
{
kArrayList list = kNULL;
//call kArrayList_Construct, and check the returned status value; if the status value is not kOK,
//return from this function, propagating the status value to the caller
kCheck(ArrayList_Construct(&list, kTypeOf(k32s), 0, kNULL));
//will not get here if an error occurred
//...
return kOK;
}

Other error-handling macros are provided to simulate the structure of exception handling. For example, kTry/kCatch:

kStatus TestFunction()
{
kArrayList list = kNULL;
kStatus exception;
kTry
{
//call kArrayList_Construct, and test the returned status value; if the status value is not kOK,
//jump to the catch block, propagating the status value to the exception handler
kTest(ArrayList_Construct(&list, kTypeOf(k32s), 0, kNULL));
//will not get here if an error occurred
//...
}
kCatch(&exception)
{
//can perform error handling here
LogTheError(exception);
//exit the catch block; if the status value passed to kEndCatch is not kOK, then return from this function,
//propagating the status value to the caller
kEndCatch(exception);
}
return kOK;
}

Or kTry/kFinally, which can be used to perform clean-up regardless of whether an error has been detected:

kStatus TestFunction()
{
kArrayList list = kNULL;
kTry
{
//call kArrayList_Construct, and test the returned status value; if the status value is not kOK,
//jump to the finally block
kTest(ArrayList_Construct(&list, kTypeOf(k32s), 0, kNULL));
//will not get here if an error occurred
//...
}
kFinally
{
//can perform any clean-up here
kObject_Destroy(list);
//exit the finally block; if an error occurred in the try block, the status value will be
//propagated to the caller
kEndFinally();
}
return kOK;
}

kTry/kCatch and kTry/kFinally are the most common forms of exception-handling in Zen. However, an extended form is provided that allows kCatch and kFinally behaviours to be combined:

kStatus TestFunction()
{
kArrayList list = kNULL;
kStatus exception;
kTry
{
//call kArrayList_Construct, and test the returned status value; if the status value is not kOK,
//jump to the catch block
kTest(ArrayList_Construct(&list, kTypeOf(k32s), 0, kNULL));
//will not get here if an error occurred
//...
}
kCatchEx(&exception)
{
//can perform error handling here
LogTheError(exception);
//exit the catch block;
kEndCatchEx(exception);
}
kFinallyEx
{
//can perform any clean-up here
kObject_Destroy(list);
//exit the finally block; if an error occurred in the try block, and was not handled in the
//catch block, the status value will be propagated to the caller
kEndFinallyEx();
}
return kOK;
}

In the extended form, an "Ex" suffix is used to distinguish kCatchEx from kCatch, kFinallyEx from kFinally, etc.

In all of the exception-handling methods, the kTry and kTest macros have the same behavior. kTry is always used to start an exception-handling block, and kTest is always used to check status values within a kTry block. The use of kTest within a kTry block is analogous to the use of kCheck anywhere else.

Because the Zen exception-handling macros are implemented with labels and local jumps (goto), it is efficient to generate exceptions and efficient to handle them. Accordingly, there is no need to avoid Zen exception-handling logic in performance-critical sections. However, one limitation of the Zen exception-handling macros is that only a single exception-handling block is permitted per function. This prevents the nesting of exception logic within a single function.

See also
  kStatus, kTry, kTest, kCatch, kEndCatch, kFinally, kEndFinally, kCatchEx, kEndCatchEx, kFinallyEx, kEndFinallyEx