INFORMIX-ESQL/C Programmer's Manual Using Informix Libraries

To create a dynamic thread library, you must define routines for every threaded operation that ESQL/C performs and you must register those functions with ESQL/C. The following list shows all of the functions that a multithreaded ESQL/C application requires and describes what each function must do.

• mint ifxOS_th_once(ifxOS_th_once_t *pblock, ifxOS_th_initroutine_t pfn, int *init_data)

This routine executes the initialization routine pfn(). Execute the pfn() functions only once, even if they are called simultaneously by multiple threads or multiple times in the same thread. The pfn() routine is equivalent to the DCE pthread_once(), or the POSIX pthread_once() routines.

The init_data variable is used for thread packages that do not have a pthread_once() type routine, such as Solaris Kernel Threads. The routine can be simulated as follows using init_data as a global variable initialized to 0.

if (!*init_data)
{
mutex_lock(pblock);
if (!*init_data)
{
(*pfn)();
*init_data = 1;
}
mutex_unlock(pblock);
}
return(0);

• mint ifxOS_th_mutexattr_create(ifxOS_th_mutexattr_t *mutex_attr)

This function creates a mutex attributes object that specifies the attributes of mutexes when they are created. The mutex attributes object is initialized with the default value for all of the attributes defined by the user's implementation. This routine is equivalent to the DCE pthread_mutexattr_create(), or the POSIX pthread_mutexattr_init() routines. If a thread package does not support mutex attribute objects, the mutex attribute routines can be no-ops.

• mint ifxOS_th_mutexattr_setkind_np(ifxOS_th_mutexattr_t *mutex_attr, int kind)

This routine sets the mutex type attribute that is used when a mutex is created. The mutex attribute mutex_attr is set to type kind. For DCE, this routine is pthread_mutexattr_setkind_np().

• mint ifxOS_th_mutexattr_delete(ifxOS_th_mutexattr_t *mutex_attr)

This routine deletes the mutex attribute object mutex_attr. This routine should have the same functionality as the DCE pthread_mutexattr_delete(), or the POSIX pthread_mutexattr_destroy() routines.

• mint ifxOS_th_mutex_init(ifxOS_th_mutex_t *mutexp, ifxOS_th_mutexattr_t mutex_attr)

This routine creates a mutex and initializes it to the unlocked state. This routine should have the same functionality as the DCE pthread_mutex_init(), or the POSIX pthread_mutex_init() routines.

• mint ifxOS_th_mutex_destroy(ifxOS_th_mutex_t *mutexp)

This routine deletes a mutex. The mutex must be unlocked before it is deleted. This routine should have the same functionality as the DCE pthread_mutex_destroy(), or the POSIX pthread_mutex_destroy() routines.

• mint ifxOS_th_mutex_lock(ifxOS_th_mutex_t *mutexp)

This routine locks an unlocked mutex. If the mutex is already locked, the calling thread should wait until the mutex becomes unlocked. This routine should have the same functionality as the DCE pthread_mutex_lock(), or the POSIX pthread_mutex_lock() routines.

• mint ifxOS_th_mutex_trylock(ifxOS_th_mutex_t *mutexp)

If the mutex is successfully locked, it returns the value 1, if the mutex is locked by another thread, it returns the value 0.

This routine should have the same functionality as the DCE pthread_mutex_trylock() routine.

• mint ifxOS_th_mutex_unlock(ifxOS_th_mutex_t *mutexp)

This routine unlocks the mutex mutexp. If threads are waiting to lock this mutex, the implementation defines which thread receives the mutex. This routine should have the same functionality as the DCE pthread_mutex_unlock(), or the POSIX pthread_mutex_unlock() routines.

• mint ifxOS_th_condattr_create(ifxOS_th_condattr_t *cond_attr)

This routine creates an object that is used to specify the attributes of condition variables when they are created. Initialize the object with the default value for all of the attributes defined by the user's implementation. This routine should have the same functionality as the DCE pthread_condattr_create(), or the POSIX pthread_condattr_init() routines.

• mint ifxOS_th_cond_init(ifxOS_th_cond_t *condp, ifxOS_th_condattr_t cond_attr)

This routine creates and initializes a condition variable. It should have the same functionality as the DCE pthread_cond_init(), or the POSIX pthread_cond_init() routines.

• mint ifxOS_th_condattr_delete(ifxOS_th_condattr_t *cond_attr)

This routine deletes the condition variable attribute object cond_attr. The routine should have the same functionality as the DCE pthread_condattr_delete(), or POSIX pthread_condattr_destroy() routines.

• mint ifxOS_th_cond_destroy(ifxOS_th_cond_t *condp)

This routine deletes the condition variable condp. The routine should have the same functionality as the DCE pthread_cond_destroy(), or the POSIX pthread_cond_destroy() routines.

• mint ifxOS_th_cond_timedwait(ifxOS_th_cond_t *sleep_cond, ifxOS_th_mutex_t *sleep_mutex, ifxOS_th_timespec_t *t)

This routine causes a thread to wait until either the condition variable sleep_cond is signaled or broadcast, or the current system clock time becomes greater than or equal to the time specified in t. The routine should have the same functionality as the DCE pthread_cond_timedwait(), or the POSIX pthread_cond_timedwait() routines.

• mint ifxOS_th_keycreate(ifxOS_th_key_t *allkey, ifxOS_th_destructor_t AllDestructor)

This routine generates a unique value that identifies a thread-specific data value. The routine should have the same functionality as the DCE pthread_keycreate(), or the POSIX pthread_key_create() routines.

• mint ifxOS_th_getspecific(ifxOS_th_key_t key, ifxOS_th_addr_t *tcb)

This routine obtains the thread-specific data associated with the key. The routine should have the same functionality as the DCE pthread_getspecific(), or the POSIX pthread_getspecific() routines.

• mint ifxOS_th_setspecific(ifxOS_th_key_t key, ifxOS_th_addr_t tcb)

This routine sets the thread-specific data in the tcb associated with the key for the current thread. If a value is already defined for key in the current thread, the new value is substituted for the existing value. The routine should have the same functionality as the DCE pthread_setspecific(), or the POSIX pthread_setspecific() routines.

You can create typedefs for the data types in the preceding functions to the equivalent data types in your thread package, or you can use the appropriate data type from the thread package instead of the ifxOS_ version. The following list includes all the data types that the preceding functions use:

• ifxOS_th_mutex_t

This structure defines a mutex object: pthread_mutex_t in DCE and POSIX.

• ifxOS_th_mutexattr_t

This structure defines a mutex attributes object called pthread_mutexattr_t in DCE and POSIX. If mutex attribute objects are unsupported in your thread package (for instance, Solaris Kernel Threads), you can assign them a data type of mint.

• ifxOS_th_once_t

This structure allows client initialization operations to guarantee mutually exclusive access to the initialization routine, and to guarantee that each initialization is executed only once. The routine should have the same functionality as the pthread_once_t structure in DCE and POSIX.

• ifxOS_th_condattr_t

This structure defines an object that specifies the attributes of a condition variable: pthread_condattr_t in DCE and POSIX. If this object is unsupported in your thread package (for instance, Solaris Kernel Threads), you can assign it a data type of mint.

• ifxOS_th_cond_t

This structure defines a condition variable called pthread_cond_t in DCE and POSIX.

• ifxOS_th_timespec_t

This structure defines an absolute time at which the ifxOS_th_cond_timedwait() function should time out if a condition variable has not been signaled or broadcast. This structure is timespec_t in DCE and POSIX.

• ifxOS_th_key_t

This structure defines a thread-specific data key used in the ifxOS_th_keycreate(), ifxOS_th_setspecific() and ifxOS_getspecific() routines. This structure is pthread_key_t in DCE and POSIX.

• ifxOS_th_addr_t

This structure defines an address that contains data to be associated with a thread-specific data key of type ifxOS_th_key_t. The ifxOS_th_addr_t structure is equivalent to pthread_addr_t in DCE. You can specify void * as an alternative that can be used for thread packages (such as POSIX) that do not define such a structure.

The following example uses the Solaris Kernel Threads package to demonstrate how to set up a dynamic-thread library. The first task is to define the 17 dynamic-thread functions that the shared and/or static library needs. In this example, the file is called dynthr.c:

/* Prototypes for the dynamic thread functions */

mint ifx_th_once(mutex_t *pblock, void (*pfn)(void), mint *init_data);
mint ifx_th_mutexattr_create(mint *mutex_attr);
mint ifx_th_mutexattr_setkind_np(mint *mutex_attr, mint kind);
mint ifx_th_mutexattr_delete(mint *mutex_attr);
mint ifx_th_mutex_init(mutex_t *mutexp, mint mutex_attr);
mint ifx_th_mutex_destroy(mutex_t *mutexp);
mint ifx_th_mutex_lock(mutex_t *mutexp);
mint ifx_th_mutex_trylock(mutex_t *mutexp);
mint ifx_th_mutex_unlock(mutex_t *mutexp);
mint ifx_th_condattr_create(mint *cond_attr);
mint ifx_th_cond_init(cond_t *condp, mint cond_attr);
mint ifx_th_condattr_delete(mint *cond_attr);
mint ifx_th_cond_destroy(cond_t *condp);
mint ifx_th_cond_timedwait(cond_t *sleep_cond, mutex_t *sleep_mutex, timestruc_t

*t);
mint ifx_th_keycreate(thread_key_t *allkey, void (*AllDestructor)(void *));
mint ifx_th_getspecific(thread_key_t key, void **tcb);
mint ifx_th_setspecific(thread_key_t key, void *tcb);

/*
* The functions . . . *
* */

mint ifx_th_once(mutex_t *pblock, void (*pfn)(void), mint *init_data)
{
if (!*init_data)
{
mutex_lock(pblock);
if (!*init_data)
{
(*pfn)();
*init_data = 1;
}
mutex_unlock(pblock);
}
return(0);
}

/* Mutex attributes are not supported in solaris kernel threads *
* The functions must be defined anyway, to avoid accessing *
* a NULL function pointer. */

mint ifx_th_mutexattr_create(mint *mutex_attr)
{
*mutex_attr = 0;
return(0);
}

/* Mutex attributes are not supported in solaris kernel threads */
mint ifx_th_mutexattr_setkind_np(mint *mutex_attr, mint kind)
{
*mutex_attr = 0;
return(0);
}

/* Mutex attributes are not supported in solaris kernel threads */
mint ifx_th_mutexattr_delete(mint *mutex_attr)
{
return(0);
}

mint ifx_th_mutex_init(mutex_t *mutexp, mint mutex_attr)
{
return(mutex_init(mutexp, USYNC_THREAD, (void *)NULL));
}

mint ifx_th_mutex_destroy(mutex_t *mutexp)
{
return(mutex_destroy(mutexp));
}

mint ifx_th_mutex_lock(mutex_t *mutexp)
{
return(mutex_lock(mutexp));
}
/* Simulate mutex_trylock using mutex_lock */

mint ifx_th_mutex_trylock(mutex_t *mutexp)
{
mint ret;

ret = mutex_trylock(mutexp);
if (ret == 0)
return(1); /* as per the DCE call */
if (ret == EBUSY)
return(0); /* as per the DCE call */
return(ret);
}

mint ifx_th_mutex_unlock(mutex_t *mutexp)
{
return(mutex_unlock(mutexp));
}

/* Condition attributes are not supported in solaris kernel threads */
mint ifx_th_condattr_create(mint *cond_attr)
{
*cond_attr = 0;
return(0);
}

mint ifx_th_cond_init(cond_t *condp, mint cond_attr)
{
return(cond_init(condp, USYNC_THREAD, (void *)NULL));
}

mint ifx_th_condattr_delete(int *cond_attr)
{
return(0);
}

mint ifx_th_cond_destroy(cond_t *condp)
{
return(cond_destroy(condp));
}

mint ifx_th_cond_timedwait(cond_t *sleep_cond, mutex_t *sleep_mutex,timestruc_t
*t)
{
return(cond_timedwait(sleep_cond, sleep_mutex, t));
}

mint ifx_th_keycreate(thread_key_t *allkey, void (*AllDestructor)(void *))
{
return(thr_keycreate(allkey, AllDestructor));
}

mint ifx_th_getspecific(thread_key_t key, void **tcb)
{
return(thr_getspecific(key, tcb));
}

mint ifx_th_setspecific(thread_key_t key, void *tcb)
{
return(thr_setspecific(key, tcb));

Your ESQL/C application must use the ifxOS_set_thrfunc() function to register the dynamic thread functions with ESQL/C. The following declaration describes the ifxOS_set_thrfunc() function.

mint ifxOS_set_thrfunc(mint func, mulong (*funcptr)())

The first parameter, func, is a mint that indexes the function being registered. The second parameter is the name of the function that is being registered.

You must call ifxOS_set_thrfunc() once for each of the 17 ifxOS functions listed in Creating a Dynamic Thread Library on UNIX Operating Systems.

The ifxOS_set_thrfunc() function returns 0 if it successfully registers the function and -1 if it fails to register the function. For example, to register the user-defined function my_mutex_lock() as the ifxOS_th_mutex_lock routine, you use the following call:

if (ifxOS_set_thrfunc(TH_MUTEX_LOCK, (mulong (*)())my_mutex_lock) == -1)

TH_MUTEX_LOCK is defined in sqlhdr.h and tells the client to call my_mutex_lock() whenever it needs to lock a mutex.

The following list shows the indexes and the functions they register.

The following function, dynthr_init(), which is also defined in dynthr.c, registers the 17 functions defined in Creating a Dynamic Thread Library on UNIX Operating Systems. FUNCFAIL is defined to be -1.

dynthr_init()
{
if (ifxOS_set_thrfunc(TH_ONCE, (mulong (*)())ifx_th_once) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_MUTEXATTR_CREATE,
(mulong (*)())ifx_th_mutexattr_create) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_MUTEXATTR_SETKIND,
(mulong (*)())ifx_th_mutexattr_setkind_np) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_MUTEXATTR_DELETE,
(mulong (*)())ifx_th_mutexattr_delete) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_MUTEX_INIT,
(mulong (*)())ifx_th_mutex_init) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_MUTEX_DESTROY,
(mulong (*)()) ifx_th_mutex_destroy) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_MUTEX_LOCK,
(mulong (*)()) ifx_th_mutex_lock) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_MUTEX_UNLOCK,
(mulong (*)())ifx_th_mutex_unlock) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_MUTEX_TRYLOCK,
(mulong (*)())ifx_th_mutex_trylock) == FUNCFAIL)
return FUNCFAIL;
if (ifxOS_set_thrfunc(TH_CONDATTR_CREATE,
(mulong (*)())ifx_th_condattr_create) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_CONDATTR_DELETE,
(mulong (*)())ifx_th_condattr_delete) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_COND_INIT,
(mulong (*)())ifx_th_cond_init) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_COND_DESTROY,
(mulong (*)())ifx_th_cond_destroy) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_COND_TIMEDWAIT,
(mulong (*)())ifx_th_cond_timedwait) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_KEYCREATE,
(mulong (*)())ifx_th_keycreate) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_GETSPECIFIC,
(mulong (*)())ifx_th_getspecific) == FUNCFAIL)
return FUNCFAIL;

if (ifxOS_set_thrfunc(TH_SETSPECIFIC,
(mulong (*)())ifx_th_setspecific) == FUNCFAIL)
return FUNCFAIL;
return 0;

}

The following C-shell command sets THREADLIB to specify a user-defined thread package:

setenv THREADLIB DYNAMIC

You must compile dynthr.c into a shared or static library. The following example illustrates how to compile a shared or static library on a workstation running the Solaris operating system:

% cc -c -DIFX_THREAD -I$INFORMIXDIR/incl/esql -D_REENTRANT -K pic dynthr.c

% ld -G -o libdynthr.so dynthr.o

% cp libdynthr.so /usr/lib <== as root

You can also use the $LD_LIBRARY_PATH environment variable:

% cc -c -DIFX_THREAD -I$INFORMIXDIR/incl/esql -D_REENTRANT -K pic dynthr.c

% cp dynthr.so <some directory>

% setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:<some directory>

To compile dynthr.c into a static library, perform the following tasks (on Solaris):

% cc -c -DIFX_THREAD -I$INFORMIXDIR/incl/esql -D_REENTRANT dynthr.c

% ar -cr dynthr.a dynthr.o

You must update your application, test.ec, to call the dynthr_init() routine first, or none of the thread functions will be registered.

void main(argc , argv )

int argc;

char *argv[] ;

{ 	/* begin main */

         

	/* First, set up the dynamic thread library */

         

	dynthr_init();

         

	/* Rest of program */

         

	EXEC SQL database stores7;
	

}

You must compile the application using the -thread and the -l preprocessor options. The -thread option indicates that you are linking thread-safe libraries instead of the default Informix shared libraries. The -l option allows you to specify system libraries that you want to link. Finally, you compile your application, link libdynthr.so and run it, as shown in the following example:

% setenv THREADLIB "dynamic"
% esql -thread -ldynthr test.ec -o test.exe
% test.exe