A cancel handler is somewhat similar to a pthread cancelation cleanup handler; however, a cancel handler runs whenever the stack frame or function that it was registered for ends in any way other than a normal return. Pthread cancelation cleanup handlers run only when the thread is terminated using pthread_exit(), pthread_cancel(), or return from the threads start routine.

Also, the cancel handler is guaranteed to run for all conditions that cause the stack frame to end (other than return), like thread termination, job termination, calls to exit(), abort(), exceptions that percolate up the stack and cancel stack frames, etc.... Similarly, C++ destructors for automatic C++ objects are guaranteed to run when the stack frame (function) or scope that it was registered in ends in any way.

These mechanisms provide a very powerful and guaranteed method to ensure that your application can always clean up its resources. With the added power of these mechanisms that the AS/400 provides, its easy for your application to cause a deadlock.

For example

Assume your application has a function foo(), that registers a cancel handler called cleanup(). The function foo() is called by multiple threads in your application. Your application is ended abnormally with a call to abort() or by system operator intervention (the ENDJOB *IMMED) CL command.

When this job end condition occurs, every thread is immediately terminated. When the system is terminating a thread by terminating each call stack entry in the thread, it eventually reaches the function foo() in that thread. When function foo() is reached, the system recognizes that it must not remove that function from the call stack without running the function cleanup(), the system runs cleanup().

Since your application is multi-threaded, all of the job ending and cleanup processing proceeds in parallel in each thread. Also, since abort() or ENDJOB *IMMED was used, the current state and location of each thread in your application is indeterminate. When your cleanup() function runs, it is very difficult for your application to correctly assume that any specific cleanup can be done. Any resources that the cleanup() function attempts to acquire may be held by other threads in the process, other jobs in the system, or possibly by the same thread running the cleanup() function. The state of application variables or resources that your application manipulates may be in an inconsistent state, because the call to abort() or ENDJOB *IMMED asynchronously interrupted every thread in the process at the same time. Its very easy for your application to deadlock when running the cancel handlers or C++ destructors.

Do not attempt to acquire locks or resources in cancel handlers or C++ automatic object destructors without preparing for the possibility that the resources cannot be acquired.

Neither a cancel handler nor a destructor for a C++ object can prevent the call stack entry from being terminated, but the termination of the call stack entry (and therefore the job or thread) will be delayed until the cancel handler or destructor completes.

If the cancel handler or destructor does not complete, the system will not continue terminating the call stack entry (and possibly the job or thread). The only alternative at this point is to use the WRKJOB CL command (option 20) to end the thread, or the ENDJOB *IMMED CL command. Since any remaining cancel handlers are still guaranteed to run, if the ENDJOB *IMMED command was the mechanism that caused the cancel handlers to run in the first place, the only option left is the ENDJOBABN CL command.

The ENDJOBABN CL command is not recommended., the ENDJOBABN command causes the job to be terminated with no further cleanup allowed (application or operating system). If the application is hung trying to access certain operating system resources, those resources could be damaged. If there are operating system resources damaged, you may be required to take various reclaim, deletion, or recovery steps, and in extreme conditions, restart the system.

Recommendations

If you want to do cleanup of your job or application, you could use one of the following mechanisms:

• If you want to do process or activation group level cleanup for normal termination, use the C atexit() function to register your cleanup function. The atexit() function provides a mechanism to run cleanup after the activation group (and possibly the threads) are terminated. The complexity will be significantly reduced.
• If you always want a chance to do process level or activation group cleanup in all cases (normal and abnormal) you could use the `Register Activation Group Exit' (CEE4RAGE()) system API. The CEE4RAGE() function provides a mechanism to run cleanup after the activation group (and possibly the threads) are terminated. The complexity will be significantly reduced.
• Cancel handlers can be used safely. Simplify your cancel handlers so that they only unlock or release resources and don't attempt to acquire any new resources or locks.
• Remove your cancel handlers, and create a CL command, program or tool that terminates your application in a more controlled fashion.
  • One possibility would be a tool that uses a signal to terminate the application. When the signal comes in, your application can get control in a single location (preferably by using the sigwait() API to safely and synchronously get the signal), and then perform some level of cleanup, and then exit() or abort() the application from within. Often this is sufficient to remove the complexity.
  • Another possibility would be to use the ENDJOB *CNTRLD CL command, and have your application dedicate a thread to watching for the controlled end condition. The application thread can use the QUSRJOBI (Get Job Information) or the QWCRTVCA (Retrieve Current Attributes) APIs to look at the `End Status' information associated with your job. The 'End Status' will indicate that the job is ending in a controlled fashion, and your application can take safe and synchronous steps to clean up and exit. In a future release, support will be added to the system such hat when the ENDJOB *CNTRLD CL command is used, and the target job has a signal handler for the SIGTERM signal, the SIGTERM signal will be sent to the process. This will allow your application to terminate normally.
  • Other IPC mechanisms can also be used to indicate that your application should terminate in a safe and controlled fashion.
• If you want to do thread level cleanup, use the pthread APIs like pthread_cleanup_push(), pthread_cleanup_pop(), pthread_key_create(), etc.. to create cancelation cleanup functions that run when the thread terminates under normal conditions. Many times, your cleanup functions won't need to run when the job ends. The most common use for these functions is to free heap storage or unlock resources. Unlocking resources is safe to do in a cancel handler, and there is no need to free() heap storage when the entire job is ending anyway.