Implementing the cancel callback

Your UDx can implement a cancel() callback function. OpenText™ Analytics Database calls this function if the query that invoked the UDx has been canceled.

You usually implement this function to perform an orderly shutdown of any additional processing that your UDx spawned. For example, you can have your cancel() function shut down threads that your UDx has spawned or signal a third-party library that it needs to stop processing and exit. Your cancel() function should leave your UDx's function class ready to be destroyed, because the database calls the UDx's destroy() function after the cancel() function has exited.

A UDx's default cancel() behavior is to do nothing.

The contract for cancel() is:

• The database will call cancel() at most once per UDx instance.

• The database can call cancel() concurrently with any other method of the UDx object except the constructor and destructor.

• The database can call cancel() from another thread, so implementations should be thread-safe.

• The database will call cancel() for either an explicit user cancellation or an error in the query.

• The database does not guarantee that cancel() will run to completion. Long-running cancellations might be aborted.

The call to cancel() is not synchronized in any way with your UDx's other functions. If you need your processing function to exit before your cancel() function performs some action (killing threads, for example), you must have the two function synchronize their actions.

The database always calls destroy() if it called setup(). Cancellation does not prevent destruction.

See C++ example: cancelable UDSource for an example that implements cancel().