Multithreading

How to: Enable Context-Safety for Multithreaded Programs Reference: Thread-Safe API Considerations

Thread-safe API support allows a multithreaded program to create separate but complete environments, each having the ability to specify its own configuration and defaults. All program activities are based within the context created by each thread and do not interfere with any other context, to the extent permitted by the physical protocol layers. Some physical protocols share resources, and thus are not appropriate for multiple context use.

The API can operate in two modes:

• Multiple contexts. A context includes all operations taking place on an EID between the EDAINIT() call that creates the EID and the EDATERM call that destroys it. In API SQL, a program can now create and use multiple contexts. Each context can have its own communications configuration file, defaults, and trace modes, and operates independently of any other context.

Multiple thread applications can assign a thread to a context without requiring additional work by the application. This approach is useful to applications that operate as servers, managing adapters as independent users.

• Multiple sessions within a context. In this mode, two or more threads operate within a single context, each managing an operation through an SCB.

The two modes can be mingled. This allows multiple threads to operate simultaneously within each created context.

Multiple context programming requires no special techniques by the application if only a single SCB is used for each context. Multiple-thread programming requires that you instruct the API to manage threads.

Since a multithreading environment may not be able to maintain addressability through server callbacks, the EDASET variable - EDA_VAR_USERAREA (158) - enables an application to store a value into the EDA_ID. This value can be retrieved during the callback using EDAINSPECT. It helps to assign a pointer to your own context information here, making this data available to callback routines. The callback block contains the EDA_ID for which the callback is being made.

Procedure: How to Enable Context-Safety for Multithreaded Programs

To enable the thread-safe API, issue an EDASET call for the variable EDA_VAR_AUTOLOCK (305) immediately following the EDAINIT in the EDAPINIT call. This setting is not required when issuing multiple EIDs that have only a single SCB each.

Setting AUTOLOCK causes the API to apply appropriate locking during its operation. This allows users to intermingle operations on a single EDA_ID over several threads, but it adds the benefit of lock management.

Reference: Thread-Safe API Considerations

The following limitations apply:

• Only one thread can operate against an SCB at a time, except that EDAQUIT() may be called against the SCB on a thread other than the one waiting for output. If more than one thread is operating against an SCB at the same time, the developer needs to use a thread synchronization method.
• An SQL operation on an SCB cannot be started until EDACONNECT returns with a successful status.
• The EDACALLBACK for tracing is not entered locked. If serialization is required within this callback, for example, to be certain that output trace lines appear in order, the callback routine must provide for appropriate locking.
• Actions taken for one EID do not apply to any other EID. For example, the EDA_VAR_AUTOLOCK setting applies only to the context for which it is issued.
• Use of the API function, EDAWAIT, is not supported.