Writing S-Functions

Exception Free Code

You can avoid this overhead by ensuring that your S-function contains entirely exception free code. Exception free code refers to code that never long-jumps. Your S-function is not exception free if it contains any routine that, when called, has the potential of long-jumping. For example, mexErrMsgTxt throws an exception (i.e., long-jumps) when called, thus ending execution of your S-function. Using mxCalloc can cause unpredictable results in the event of a memory allocation error, because mxCalloc long-jumps. If memory allocation is needed, use the stdlib.h calloc routine directly and perform your own error handling.

If you do not call mexErrMsgTxt or other API routines that cause exceptions, use the SS_OPTION_EXCEPTION_FREE_CODE S-function option. You do this by issuing the following command in the mdlInitializeSizes function.

• ssSetOptions(S, SS_OPTION_EXCEPTION_FREE_CODE);
  

Setting this option increases the performance of your S-function by allowing Simulink to bypass the exception-handling setup that is usually performed prior to each S-function invocation. You must take extreme care to verify that your code is exception free when using SS_OPTION_EXCEPTION_FREE_CODE. If your S-function generates an exception when this option is set, unpredictable results occur.

All mex* routines have the potential of long-jumping. Several mx* routines also have the potential of long-jumping. To avoid any difficulties, use only the API routines that retrieve a pointer or determine the size of parameters. For example, the following never throw an exception: mxGetPr, mxGetData, mxGetNumberOfDimensions, mxGetM, mxGetN, and mxGetNumberOfElements.

Code in run-time routines can also throw exceptions. Run-time routines refer to certain S-function routines that Simulink calls during the simulation loop (see How Simulink Interacts with C S-Functions). The run-time routines include:

• mdlGetTimeOfNextVarHit
• mdlOutputs
• mdlUpdate
• mdlDerivatives

If all run-time routines within your S-function are exception free, you can use this option:

• ssSetOptions(S, SS_OPTION_RUNTIME_EXCEPTION_FREE_CODE);
  

The other routines in your S-function do not have to be exception free.

Handling Errors

ssSetErrorStatus Termination Criteria