Initializing Applications

 Working-Storage Section.
 01 thread-id     usage pointer.
 . . .
* Initialization code executed while in single-threaded 
* mode to check if the run-time system supports 
* multi-threading or the CBL_THREAD_ routines.
     call 'CBL_THREAD_SELF' using thread-id
      on exception
*        No cbl_thread routines support
     end-call
     if return-code = 1008
*        Running in a single-threaded rts
     end-if

This example makes use of the run-time library routine CBL_THREAD_SELF to determine if the run-time system supports multi-threading.

After the application has determined that the run-time system supports multi-threading, all synchronization primitives should be be initialized using the appropriate OPEN syntax. It is easiest to do this as part of the main program, before any other threads are created within the application. However, if this not possible, either because of the way the application is designed, or because of modularity or mixed-language considerations, Micro Focus have provided a single pre-initialized mutex per program. This mutex is accessed using the CBL_THREAD_PROG_LOCK and CBL_THREAD_PROG_UNLOCK run-time library routines. Using these routines, it is possible to ensure that any handles for program -local synchronization primitives are initialized once (and only once) during the execution of the application.

The following code illustrates a sample use of these routines for program initialization while running in multi-threaded mode:

 Working-Storage Section.
 01 first-flag         pic x comp-x value 1.
    88 first-time       value 1.
    88 not-first-time   value 0.
  
* Initialization code executed while in multi-threaded mode.
* Ensures that program local data is initialized properly.

     if first-time then
         call 'CBL_THREAD_PROG_LOCK'
         if first-time then
* Initialize program local data and synchronization objects
               ...
             set not-first-time   to true
         end-if
         call 'CBL_THREAD_PROG_UNLOCK'
     end-if

Note the double checking of the first-time level-88 data item. This is a good optimization technique in multi-threaded applications. The idea of the optimization is to avoid the overhead of locking a mutex if the intended action has already been performed. In this case, if multiple threads enter the program before it is properly initialized, they will all find that first-time is true and so issue a call to CBL_THREAD_PROG_LOCK. However, only one will acquire the lock while first-time is still true. This is the thread that will do the initialization.

After the initialization is completed, and while the initializing thread still owns the lock, the first-time flag is set to false. All successive threads acquiring the lock can see that the initialization has already been done, as first-time is now false, and unlock the program immediately. Any following threads that enter after initialization will also see the first-time flag is false and will not attempt to acquire the program lock (and so reduce program entry overhead).

The flag that specifies whether initialization has occurred should as simple as possible (that is, a single byte data item).