Error Handling

<<< Session Support

Chapters

Glossary >>>

Contents

• 59.1 Introduction
• 59.2 Handling errors from Parasolid
  • 59.2.1 Using a registered error handler
  • 59.2.2 Letting the application check for non-zero error returns after each function call
  • 59.2.3 What to do when an error occurs
  • 59.2.4 Useful error tracking tools
• 59.3 User interrupt and RTE handling
  • 59.3.1 Protected and unprotected sections of code
  • 59.3.2 Available functions
  • 59.3.3 Processing interrupts
  • 59.3.4 Handling user interrupts
  • 59.3.5 Handling run time errors
• 59.4 Dealing with re-entrant functions
• 59.5 Longjumping
• 59.6 Examples
  • 59.6.1 Using an error handler that long jumps
  • 59.6.2 Using an error handler that doesn't long jump
  • Glossary

[back to top]

59.1 Introduction

This chapter tells you about the different types of error that your application might encounter, and how you can handle them. If you have not done so already, you might find it useful to read the introduction to error handling in the frustrum in the Getting Started With Parasolid manual before continuing with this chapter.

Your application is responsible for intercepting and handling error conditions that may arise when calling Parasolid. This may include any of the following types of error:

• Errors from Parasolid, in the form of non-zero PK function return values (or non-zero KI routine ifail values, if your application contains legacy KI code)
• User interrupts
• Run-time errors (RTEs), in the kernel or the frustrum

You must handle the first of these, and, depending on the design of your application, you may need to handle one or both of the others.

The way that you handle any given error depends on both the design of your application, and the type of error being handled.

• You can handle Parasolid errors by registering an error handler with Parasolid, or by explicitly examining the return value of every PK function call.
• You can handle user interrupts by registering an interrupt handler with the operating system, and using PK_SESSION_abort.
• You can handle RTEs by registering a run-time error handler with the operating system, and using PK_SESSION_abort.

If you are handling both user interrupts and RTEs, you can use the same signal handler for both types of error, if you wish.

You are highly recommended to implement rollback functionality in your application in order to tidy up a session after severe errors. See Chapter 41, "Partitions and Rollback", for details. The rollback functions are supplied to Parasolid using PK_DELTA_register_callbacks.

The rest of this chapter is structured as follows:

• Section 59.2, "Handling errors from Parasolid" describes how you can handle errors returned from calls to PK functions.
• Section 59.3, "User interrupt and RTE handling" describes how you can implement user interrupt and run-time error handling in your application.
• Section 59.4, "Dealing with re-entrant functions" describes how to handle errors in re-entrant functions.
• Section 59.5, "Longjumping", describes how to use longjumping techniques to handle any of these errors.
• Section 59.6, "Examples" gives some code examples of error handling.

Further information

You can find more information about error handling in the following places:

• Further frustrum-specific information is available in the Downward Interfaces manual
• Specific PK error codes are listed in the PK Interface Programming Reference Manual
• Specific KI error codes are listed in the KI Programming Reference Manual

[back to top]

59.2 Handling errors from Parasolid

Every PK function returns an error code as the function value to indicate the result of calling that function. If this value is PK_ERROR_no_errors (0) the function has completed successfully and your application can proceed.

If the return value is anything else, then the function has failed to complete. Each numerical value indicates a predictable error, and your application needs to take one of the following courses of action, depending on what that value is, and how severe the error is in this context:

• Continue with the current Parasolid session
• Rollback with the current Parasolid session to a safe point before the error occurred.
• Shut down Parasolid completely.

Choosing how to handle Parasolid errors

There are two approaches to handling errors from Parasolid.

• You can supply an error handler in your application and register it with Parasolid. This error handler is automatically invoked when a PK function is about to return a failure. See Section 59.2.1.
• Your application allows each PK function to complete, examines the return value, and performs its own error recovery. See Section 59.2.2.

The strategy you choose probably depends on how errors are handled by the rest of your application. If possible, you are recommended not to mix the two strategies, unless you never longjump in your application code.

Whichever strategy you choose, the same action needs to be taken. This action depends on the severity of the error, as supplied in the error standard form. See Section 59.2.3, "What to do when an error occurs" for more details.

Looking up PK error code values

The numerical values and meanings of PK error codes are listed in two formats in the PK Interface Programming Reference Manual (Part 2 - Interface Structures, Tokens & Error Codes):

• Appendix C, "PK Error Codes (Numeric)"
• Appendix D, "PK Error Codes (Alphabetic)"

In order to handle a given error, you must look up the appropriate error code in one of these lists and write your error handling code appropriately. There is no way to extract the meaning of a particular error code programmatically from the PK. You can also find PK error codes listed in the file parasolid_kernel.h .

[back to top]

59.2.1 Using a registered error handler

In order to use a registered error handler, you need to do the following:

• Provide the necessary error handler code as part of your application.
• Register the error handler with Parasolid, using PK_ERROR_register_callbacks.

Once registered, the error handler is automatically invoked if a PK function is about to return an error. The error handler is passed a standard structure (PK_ERROR_sf_t) containing the following data:

• The function returning the error
• The error severity
• The specific error code
• Other information to assist with isolating the problem

The error handler then takes appropriate action on the basis of this information. See Section 59.2.3, "What to do when an error occurs".

[back to top]

59.2.2 Letting the application check for non-zero error returns after each function call

The main difference between using a registered error handler and letting your application handle PK errors is that a registered error handler is invoked automatically by Parasolid before a non-zero error code is returned, whereas your code needs to examine error codes explicitly if no error handler is registered.

When you are not using a registered error handler, you need to do the following:

• Ensure that your application examines the return value of each PK function call.
• Ensure that your application performs the necessary recovery actions whenever the return value is non-zero.

You should use PK_ERROR_ask_last and PK_ERROR_clear_last (see Section 59.2.4) to manage information about PK errors. As with a registered error handler, your code should then take appropriate action on the basis of this information. See Section 59.2.3, "What to do when an error occurs".

[back to top]

59.2.3 What to do when an error occurs

Although the general principles are the same, the precise details of what you need to do when a Parasolid error occurs depend on whether you use a registered error handler, and whether you choose to longjump on an error.

There are three error severity levels that your application has to handle:

The error severity is returned in the PK_ERROR_sf_t structure that is passed to the error handler. You can also use PK_ERROR_ask_last to determine the severity of a given error: see Section 59.2.4.

Using no error handler

If you decide to examine error codes in your application code, the sequence of events is as follows:

Figure 59-1 Handling a Parasolid error when there is no registered error handler

When no error handler is registered, the return value of every PK function call must be examined, and appropriate action taken if the result is anything other than PK_ERROR_no_errors. Calls to PK functions in your application code can be structured as shown in the pseudo-code below:

result = PK_function_1
if (result != PK_ERROR_no_errors)
    <handle error>

result = PK_function_2
if (result != PK_ERROR_no_errors)
    <handle error>

result = PK_function_3
if (result != PK_ERROR_no_errors)
    <handle error>

. . .

Using an error handler that returns to the function

If you register an error handler, and decide to return to the failing PK function whenever an error occurs, the sequence of events is as follows.

Figure 59-2 Handling a Parasolid error with a registered error handler that returns to the failing function

When you register an error handler and then return to the failing PK function, you still need to check the return value of every PK function call. The main difference to the structure of your code between this strategy and using no error handler is that you do not need to explicitly handle every error in your application code. Calls to PK functions in your application code can be structured as shown in the pseudo-code below:

<register error handler>

result = PK_function_1

if (result == PK_ERROR_no_errors)
result = PK_function_2

if (result == PK_ERROR_no_errors)
result = PK_function_3

. . .

If you return to the failing PK function, then

• The function returns an error code to your application, to enable your application to determine what action is necessary.
• The values of any return arguments for the function are undefined.
• Any memory allocated by Parasolid for return arguments is freed.

Using an error handler that longjumps

If you register an error handler, and decide to longjump whenever an error occurs, the sequence of events is as follows.

Figure 59-3 Handling a Parasolid error with a registered error handler always longjumps

The advantage of this method is that it allows you to group calls to PK functions into meaningful clusters in your application. You do not need to explicitly examine the return value of each function in your application. Calls to PK functions in your application code can be structured as shown in the pseudo-code below:

<register error handler>

if (setjmp(&setjmp_buffer) == 0)

  { /* group of PK function calls */
    PK_function_1
    PK_function_2
    PK_function_3
  }

else
  { /* safe point - get here from error handler */
    <tidy-up code>
  }

[back to top]

59.2.4 Useful error tracking tools

This section describes a number of error tracking tools that are particularly useful in the following cases:

• If you handle PK function errors in your application code, rather than registering an error handler.
• If you need to override the registered error handler, so that you can handle specific errors in your application code, but return control to a registered error handler for the majority of other cases.

[back to top]

59.3 User interrupt and RTE handling

As well as handling Parasolid errors, your application can also handle user interrupts and run-time errors (RTEs). Unlike Parasolid errors, this is not mandatory, so you can ignore this section if it is not relevant to your application design.

You can provide one or more signal handlers to cope with user interrupts, various types of RTEs and, optionally, timers:

• An interrupt handler handles user interrupts, such as when the user interrupts an executing Parasolid operation (for instance, by pressing Ctrl+C).
• A run-time error handler handles RTEs. It can be registered to handle the following errors:
• Floating point exceptions (except for floating point underflow, which should not be trapped - see Section 8.1, "Introduction" in the Parasolid Release Notes)
• Memory access errors
• A timeout handler handles timers. You can set timers in your application code to ensure that particular signals are processed. A timeout handler monitors these timers and takes appropriate action when a timer expires.

If you wish, you can use a single function to handle all these types of signal. Signal handling is specific to both the operating system and application language. Your application must register any signal handlers with the operating system. For applications written in C, please refer to the system documentation for signal-handling functionality in the C run-time library.

For both user interrupt and RTE handling, the basic principle is to use the signal handler to determine what state the kernel is in when the error occurs (using PK_SESSION_is_in_kernel), and then to take appropriate action in Parasolid and your application in order to recover gracefully from the user interrupt or RTE.

[back to top]

59.3.1 Protected and unprotected sections of code

In order to determine what action needs to be taken when a user interrupt or RTE occurs, it is important to find out what type of kernel code was executing at the time.

PK functions can be categorised as either lightweight or heavyweight.

• A lightweight function is a read only call to the PK, such as PK_BSURF_ask.
• A heavyweight function is any operation that can make changes to the model, such as PK_BODY_boolean_2.

Heavyweight functions can be further divided into unprotected and protected sections of code:

• An unprotected section is the "non-modeling" part of a heavyweight function.
• A protected section is the "modeling" part of any heavyweight function.

Lightweight functions consist of only unprotected sections.

PK_SESSION_is_in_kernel establishes whether the current function is lightweight or heavyweight, and whether the error occurred in a protected or unprotected section of code. This information determines what action Parasolid takes.

[back to top]

59.3.2 Available functions

A number of functions are available to help handle user interrupts and RTEs:

• PK_SESSION_is_in_kernel determines the state of the kernel when an error occurs
• PK_SESSION_abort tries to abort any Parasolid function that was executing when the error occurred.
• PK_SESSION_ask_function returns the name of the PK function currently being called.

PK_SESSION_is_in_kernel

Signal handlers can call PK_SESSION_is_in_kernel to determine the kernel's state when a user interrupt or RTE occurs. This function returns the following information:

• Whether execution was inside or outside the kernel when the error occurred
• If within, whether execution was in a protected or unprotected section of code (that is, could the model be changed or not)

This information is used to determine exactly what action is needed to recover gracefully from the error.

PK_SESSION_abort

Signal handlers can call PK_SESSION_abort to abort the kernel function that is executing when a user interrupt or RTE occurs. It takes a reason argument that describes the type of error for which an abort has been requested:

PK_SESSION_ask_function

Returns the name of the PK function currently being called.

[back to top]

59.3.3 Processing interrupts

Error returns from both user interrupt requests and RTEs are processed as shown in Figure 59-4. This figure illustrates the sequence of events that is common to both UI requests and RTEs. You should also refer to Section 59.3.4, "Handling user interrupts" or Section 59.3.5, "Handling run time errors", as appropriate for the type of error you are handling.

Figure 59-4 Processing the interrupt from a user interrupt request or an RTE

[back to top]

59.3.4 Handling user interrupts

If a user interrupt occurs when execution is in the kernel or the frustrum, and you have provided a signal handler to deal with user interrupts, the error handling process is as shown in Figure 59-5. User interrupt requests are made by calling PK_SESSION_abort with the error token PK_abort_user_interrupt_c.

User interrupts requests are handled by Parasolid at the next safe point in code, rather than immediately. In principle, this could mean that a user interrupt may not be acknowledged for some time, leading to delays and frustration for the user. In order to avoid this, you should set a timer before calling PK_SESSION_abort. If this timer expires before a user interrupt request is handled, then you can force Parasolid to process the request immediately by signalling a run-time error. This is done by calling PK_SESSION_abort with the error token PK_abort_runtime_error_c: see Section 59.3.5, "Handling run time errors".

If you have not provided a signal handler, then any user interrupt requests are processed in whatever manner your application's run-time library support specifies. This could mean, for instance, that user interrupt requests are ignored, or that your application exits.

Figure 59-5 Handling a user interrupt in the Parasolid kernel

[back to top]

59.3.5 Handling run time errors

If a run-time error occurs when execution is in the kernel, and you have provided a signal handler to deal with RTEs, the error handling process is as shown in Figure 59-6. Requests to handle run-time errors are made by calling PK_SESSION_abort with the error token PK_abort_runtime_error_c. Unlike user interrupts, requests to handle RTEs are processed immediately.

If an RTE occurs when execution is in the frustrum, the procedure is the same as shown in Figure 59-6, except that PK_SESSION_abort is called with the token PK_abort_frustrum_error_c, and the error code that can be returned is PK_ERROR_fru_error.

If no RTE signal handler is provided, then an RTE results in the default behavior of the run-time system. This is likely to exit your application.

Figure 59-6 Handling an RTE in the Parasolid kernel

[back to top]

59.4 Dealing with re-entrant functions

If the failing function is a recursive (re-entrant) operation called from the GO, then:

• If a longjump is performed, it must jump to a point in the application code outside the top-level Parasolid code. PK_SESSION_tidy tidies for all extant PK calls - not just the re-entrant one.
• If the error handler returns to the re-entrant operation, your application should call PK_SESSION_abort again for the top-level function and handle that appropriately, if you want the outer PK call to be aborted.

[back to top]

59.5 Longjumping

If, when handling an error of any sort, your application longjumps out of Parasolid, it must call PK_SESSION_tidy. Doing this:

• Leaves the kernel in a self-consistent state
• Frees any unused Parasolid memory

You can call PK_SESSION_tidy either before or after longjumping, but, unless you longjumped as a result of a mild error, you must call it before you call the next PK function (often a rollback command).

Many PK functions return information in an array whose space is allocated by Parasolid, together with the length of this array. If the function succeeds, your application should look at the array length to see if anything is returned. If the length is zero, then your application's pointer to the array should be set to NULL. If your application longjumps out of this function as a result of error handling, then the pointer to the array has an undefined value.

[back to top]

59.6 Examples

The examples in this section demonstrate how to handle a PK error by longjumping, and by returning to the function that has generated the error, respectively.

[back to top]

59.6.1 Using an error handler that long jumps

#include <setjmp.h>
#include <stdio.h>
#include "parasolid_kernel.h"

jmp_buf jmp_label_g;
  /* saved context to longjump to in application code */

PK_ERROR_code_t longjump_error_handler( PK_ERROR_sf_t * error_sf )
{
  /* insert application-specific tidying code here */
  PK_ERROR_code_t session_tidy_result = PK_SESSION_tidy();
  int jmp_code = (session_tidy_result == PK_ERROR_no_errors ? 1 : 2);
    /* if PK_SESSION_tidy returns an error, something is */
    /* seriously corrupted, and the application should */
    /* restart Parasolid */
  longjmp(jmp_label_g, jmp_code);
}

/* start of a sequence of possibly complex */
/* Parasolid operations                    */
PK_MARK_t mark;
error = PK_MARK_create(&mark); 
                     /* set a mark to rollback to on failure */
PK_ERROR_frustrum_t error_frustrum;
error_frustrum.handler_fn = longjump_error_handler;
PK_ERROR_register_callbacks(error_frustrum);

if ((jmp_result = setjmp(&jmp_label_g)) == 0)
  {
  PK_ATTRIB_create_empty(entity, attdef, &attrib);
  /* ... successful execution continues here,  */
  /* including other calls of PK functions ... */
  }
else
  {
  /* The error handler will longjump to here if an    */
  /* error occurs in any of the PK calls made above.  */
  if (jmp_result == 2)
    {
    /* severe error, perhaps longjump again to higher level? */
    }
  else
    {
    printf("Rolling back to before <xxx> operation");
    PK_MARK_goto(mark);
    }
  }

[back to top]

59.6.2 Using an error handler that doesn't long jump

#include <stdlib.h>
#include "parasolid_kernel.h"

PK_ERROR_code_t simple_error_handler(PK_ERROR_sf_t * error_sf)
{

/* There are some classes of errors for which local recovery */
/* is not possible, or at least not simple. These are handled*/
/* here by printing a message for the user and then exiting. */
/* More complex error recovery would in general require a    */
/* longjumping handler as described in Section 59.6.1.       */

  switch (error_sf->code)
  {
  case PK_ERROR_aborted:  /* user interrupt */
  case PK_ERROR_run_time_error:
  case PK_ERROR_system_error:
  case PK_ERROR_fatal_error:
  case PK_ERROR_unhandleable_condition:
  /* etc. */
    print_error_info
       ("About to exit after error %d\n", (int)error_sf->code);
    exit(EXIT_FAILURE);
  default:
    /* insert application-specific tidying code here */
    return error_sf->code;
  }
}

/* somewhere in the application initialization code ... */
PK_ERROR_frustrum_t error_frustrum;
error_frustrum.handler_fn = simple_error_handler;
PK_ERROR_register_callbacks(error_frustrum);
/* ... */

PK_ERROR_code_t result = PK_ATTRIB_create_empty(entity, attdef, &attrib);
if (result != PK_ERROR_no_errors)
  {
  /* Check the error code, and possibly severity (eg by   */
  /* calling PK_ERROR_ask_last), and take the appropriate */
  /* action. Errors which cannot be handled locally have  */
  /* already been dealt with */
  }

[back to top]