Thread-control Routines

The library routines for controlling threads can be used to implement threads that wait for another thread to terminate and then pick up a return value.

You should terminate any thread created using these library routines by one of the following methods:

• Exit using STOP RUN
• Exit using CBL_THREAD_EXIT
• Be killed by CBL_THREAD_KILL
• Return from the original entry point

A thread might not have been created by the thread-control routines. However, such a thread might still be known to the run-time system by the thread's use of run-time system services. Such a thread can be accessed via the thread-control library routines; it can use:

• The CBL_THREAD_LIST_START, CBL_THREAD_LIST_NEXT, and CBL_THREAD_LIST_END routines. The thread will also show up in the lists provided by these routines.
• The CBL_THREAD_IDDATA_ALLOC and CBL_THREAD_IDDATA_GET routines.
• The CBL_THREAD_SELF routine to get information on itself.
• The CBL_THREAD_SUSPEND and CBL_THREAD_RESUME routine.
• The CBL_THREAD_DETACH routine to detach itself while still alive; however this call is effectively a noop. Irrespective of any detach call, the resources of the thread from a program in another language are freed when it finishes using the run-time system and calls cobthreadtidy(). It is illegal for a thread from a program in another language to terminate without first calling cobthreadtidy().

In a mixed-language environment, any thread known to the run-time system from its use of the run-time system, but not created by the run-time system or any of the thread control routines, must do one of the following:

• Call cobthreadtidy() before terminating. This call informs the run-time system that the thread no longer needs its services and allows it to cleanup its thread-state data.
• Call cobtidy() to indicate that the COBOL run-time system will not be needed again in this application run.
• Call cobexit() to terminate the run unit.
• Not be killed by another thread calling CBL_THREAD_KILL. The user should use the kill mechanism that matches how the thread was created originally.
• Not be waited on by another thread calling CBL_THREAD_WAIT. The user should use the wait mechanism that matches how the thread was created originally.
• Not exit by using the routine CBL_THREAD_EXIT. The user should use the termination mechanism that matches how the thread was created originally.

An application can check that the run-time system used by a program supports the thread-control routines by calling either CBL_GET_OS_INFO or CBL_THREAD_SELF.

Example - Checking Which Run-time System a Program Supports

     call "CBL_THREAD_SELF" using thread-id
      on exeception
*       no cbl_thread routines support
     end-call
     if  return-code = 1008
*       running in a single-threaded-only rts
     end-if