OCILIB (C Driver for Oracle) 3.9.2
Functions
Threads and mutexes

Detailed Description

Oracle proposes a portable implementation of Mutex and Thread objects

OCILIB implements these OCI features for portable multithreading support.

Mutexes are designed for mutual exclusion between thread in order to lock resources temporarily

Thread keys can be seen as process-wide variables that have a thread-specific values. It allows to create a unique key identified by a name (string) that can store values specific to each thread.

OCILIB exposes the types OCI_Mutex, OCI_Thread

Warning:
OCILIB MUST be initialized with OCI_ENV_THREADED to enable threads support
OCI_Thread relies on Oracle API which uses natives threading capabilities of the supported platform
Using OCI_Mutex :
Example
#include "ocilib.h"

#define MAX_THREADS 50


void key_cleanup(void *str)
{
    free(str);
}

void worker(OCI_Thread *thread, void *data)
{
   const void *id = OCI_HandleGetThreadID(thread);
   char *str = malloc(50);

   sprintf(str, "thread %p !\n", id);

   OCI_ThreadKeySetValue("ID", str);

   /* ... do some more processing here... */

   str = OCI_ThreadKeyGetValue("ID");

   printf(str);
}

int main(void)
{
    OCI_Thread *th[MAX_THREADS];
    int i;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT | OCI_ENV_THREADED))
        return EXIT_FAILURE;

    OCI_ThreadKeyCreate("ID", key_cleanup);

     /* create threads */

    for (i = 0; i < MAX_THREADS; i++)
    {
        th[i] = OCI_ThreadCreate();
        OCI_ThreadRun(th[i], worker, NULL);
    }
  
    /* wait for threads and cleanup */

    for (i = 0; i < MAX_THREADS; i++)
    {
       OCI_ThreadJoin(th[i]);
       OCI_ThreadFree(th[i]);
    }

    OCI_Cleanup();
 
    return EXIT_SUCCESS;
}

Functions

OCI_EXPORT OCI_Mutex *OCI_API OCI_MutexCreate (void)
 Create a Mutex object.
OCI_EXPORT boolean OCI_API OCI_MutexFree (OCI_Mutex *mutex)
 Destroy a mutex object.
OCI_EXPORT boolean OCI_API OCI_MutexAcquire (OCI_Mutex *mutex)
 Acquire a mutex lock.
OCI_EXPORT boolean OCI_API OCI_MutexRelease (OCI_Mutex *mutex)
 Release a mutex lock.
OCI_EXPORT OCI_Thread *OCI_API OCI_ThreadCreate (void)
 Create a Thread object.
OCI_EXPORT boolean OCI_API OCI_ThreadFree (OCI_Thread *thread)
 Destroy a thread object.
OCI_EXPORT boolean OCI_API OCI_ThreadRun (OCI_Thread *thread, POCI_THREAD proc, void *arg)
 Execute the given routine within the given thread object.
OCI_EXPORT boolean OCI_API OCI_ThreadJoin (OCI_Thread *thread)
 Join the given thread.
OCI_EXPORT boolean OCI_API OCI_ThreadKeyCreate (const mtext *name, POCI_THREADKEYDEST destfunc)
 Create a thread key object.
OCI_EXPORT boolean OCI_API OCI_ThreadKeySetValue (const mtext *name, void *value)
 Set a thread key value.
OCI_EXPORT void *OCI_API OCI_ThreadKeyGetValue (const mtext *name)
 Get a thread key value.

Function Documentation

OCI_EXPORT OCI_Mutex* OCI_API OCI_MutexCreate ( void  )

Create a Mutex object.

Returns:
Mutex handle on success or NULL on failure

Definition at line 96 of file mutex.c.

OCI_EXPORT boolean OCI_API OCI_MutexFree ( OCI_Mutex mutex)

Destroy a mutex object.

Parameters:
mutex- Mutex handle
Returns:
TRUE on success otherwise FALSE

Definition at line 116 of file mutex.c.

OCI_EXPORT boolean OCI_API OCI_MutexAcquire ( OCI_Mutex mutex)

Acquire a mutex lock.

Parameters:
mutex- Mutex handle
Returns:
TRUE on success otherwise FALSE

Definition at line 157 of file mutex.c.

Referenced by OCI_PoolGetConnection().

OCI_EXPORT boolean OCI_API OCI_MutexRelease ( OCI_Mutex mutex)

Release a mutex lock.

Parameters:
mutex- Mutex handle
Returns:
TRUE on success otherwise FALSE

Definition at line 182 of file mutex.c.

Referenced by OCI_PoolGetConnection().

OCI_EXPORT OCI_Thread* OCI_API OCI_ThreadCreate ( void  )

Create a Thread object.

Returns:
Thread handle on success or NULL on failure

Definition at line 67 of file thread.c.

References OCI_ThreadFree().

OCI_EXPORT boolean OCI_API OCI_ThreadFree ( OCI_Thread thread)

Destroy a thread object.

Parameters:
thread- Thread handle
Returns:
TRUE on success otherwise FALSE

Definition at line 130 of file thread.c.

Referenced by OCI_ThreadCreate().

OCI_EXPORT boolean OCI_API OCI_ThreadRun ( OCI_Thread thread,
POCI_THREAD  proc,
void *  arg 
)

Execute the given routine within the given thread object.

Parameters:
thread- Thread handle
proc- routine to execute
arg- parameter to pass to the routine
Returns:
TRUE on success otherwise FALSE

Definition at line 192 of file thread.c.

OCI_EXPORT boolean OCI_API OCI_ThreadJoin ( OCI_Thread thread)

Join the given thread.

Parameters:
thread- Thread handle
Note:
This function waits for the given thread to finish
Returns:
TRUE on success otherwise FALSE

Definition at line 226 of file thread.c.

OCI_EXPORT boolean OCI_API OCI_ThreadKeyCreate ( const mtext *  name,
POCI_THREADKEYDEST  destfunc 
)

Create a thread key object.

Parameters:
name- Thread key name
destfunc- Thread key value destructor function
Note:
Parameter proc is optional. It's called when the thread terminates to allow the program to deal with the thread specific value of the key
Returns:
TRUE on success otherwise FALSE

Definition at line 189 of file threadkey.c.

References OCI_HashAddPointer(), and OCI_HashCreate().

OCI_EXPORT boolean OCI_API OCI_ThreadKeySetValue ( const mtext *  name,
void *  value 
)

Set a thread key value.

Parameters:
name- Thread key name
value- user value to set
Returns:
TRUE on success otherwise FALSE

Definition at line 247 of file threadkey.c.

References OCI_HashGetPointer().

OCI_EXPORT void* OCI_API OCI_ThreadKeyGetValue ( const mtext *  name)

Get a thread key value.

Parameters:
name- Thread key name
Returns:
Thread key value on success otherwise FALSE

Definition at line 271 of file threadkey.c.

References OCI_HashGetPointer().