Persistent Data and the TU_INFO_HANDLE

Because of the requirement to allow multi-threaded, simultaneous execution of Test Units, the TU functions must be written to be re-entrant, implying that statically defined variables or structure are not allowed.

Note: Static constant values are not a problem.

To illustrate the problem, imagine two threads of execution calling the same TU to run simultaneously against two device instances of the same type. Values stored in static variables would get changed in both threads of execution, probably leading to a program failure. Therefore, all variables and structures must be either defined locally as stack variables, or created using allocated memory. Without static variables, it is difficult to retain any data around from one execution of a TU to the next.

The intent of the TU_INFO_HANDLE pointer in the exectu()interface is to provide the TU writer with a pointer to a data buffer that will persist across multiple execution calls to specific Test Units. On the first call to a TU library, the TU_INFO_HANDLE pointer will be set to NULL. The first TU, TU_OPEN, must allocate the buffer and set the TU_INFO_HANDLE pointer. Data that the TU writer wants to have persist (for example, device attribute information) can then be placed within that buffer, and the pointer to the buffer will be passed back on each subsequent call to the TU library.

Because the data buffer remains allocated after the TU returns control to the calling application, it is the responsibility of the calling application to free the buffer any time that a premature termination is required, or after it calls the last TU (TU_CLOSE).

Data that should be kept in the persistent data buffer includes:

• The pdiagex_dds_t structure which contains several device attributes and is used as a parameter to the pdiag_open call.
• The PDIAG_INFO_HANDLE returned from the pdiag_open call, which is used as an input parameter to all the other device operation functions.
• An indicator of the state of the device (DIAGNOSE or NORMAL)
• Other device-attribute information obtained from Configuration Services using the pdiag_cs_get_attr function (to avoid the overhead of rerequesting it for each TU call).
• Any other information the TU writer would like to have persist from one call to the next.