Threads and mutexes

Detailed Description

OcilibCApiHashTables

Oracle proposes a portable implementation of Mutex and Thread objects.

OCILIB implements these OCI features for portable multi-threading support.

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

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

OCILIB exposes the types OCI_Mutex and OCI_Thread.

Warning

OCILIB MUST be initialized with OCI_ENV_THREADED to enable thread support.

OCI_Thread relies on the Oracle API which uses native threading capabilities of the supported platform.

Using OCI_Mutex:

• On Microsoft Windows, a thread can call OCI_MutexAcquire() more than once without any blocking. Just be sure that there is an OCI_MutexRelease() for every OCI_MutexAcquire() call.
• On Unix systems, a thread MUST call OCI_MutexRelease() after every call to OCI_MutexAcquire() in order to be able to call OCI_MutexAcquire() again. If not, it will be blocked.

Example

#include "ocilib.h"
 
#define MAX_THREADS 50
 
void err_handler(OCI_Error *err)
{
    printf("%s\n", OCI_ErrorGetString(err));
}
 
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);
 
    str = OCI_ThreadKeyGetValue("ID");
 
    printf(str);
}
 
int main(void)
{
    OCI_Thread *th[MAX_THREADS];
    int i;
 
    if (!OCI_Initialize(err_handler, 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_SYM_PUBLIC OCI_Mutex *OCI_API	OCI_MutexCreate (void)
	Create a Mutex object.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MutexFree (OCI_Mutex *mutex)
	Destroy a mutex object.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MutexAcquire (OCI_Mutex *mutex)
	Acquire a mutex lock.
OCI_SYM_PUBLIC boolean OCI_API	OCI_MutexRelease (OCI_Mutex *mutex)
	Release a mutex lock.
OCI_SYM_PUBLIC OCI_Thread *OCI_API	OCI_ThreadCreate (void)
	Create a Thread object.
OCI_SYM_PUBLIC boolean OCI_API	OCI_ThreadFree (OCI_Thread *thread)
	Destroy a thread object.
OCI_SYM_PUBLIC boolean OCI_API	OCI_ThreadRun (OCI_Thread *thread, POCI_THREAD proc, void *arg)
	Execute the given routine within the given thread object.
OCI_SYM_PUBLIC boolean OCI_API	OCI_ThreadJoin (OCI_Thread *thread)
	Join the given thread.
OCI_SYM_PUBLIC boolean OCI_API	OCI_ThreadKeyCreate (const otext *name, POCI_THREADKEYDEST destfunc)
	Create a thread key object.
OCI_SYM_PUBLIC boolean OCI_API	OCI_ThreadKeySetValue (const otext *name, void *value)
	Set a thread key value.
OCI_SYM_PUBLIC void *OCI_API	OCI_ThreadKeyGetValue (const otext *name)
	Get a thread key value.

Function Documentation

OCI_MutexCreate()

OCI_SYM_PUBLIC OCI_Mutex *OCI_API OCI_MutexCreate

(

void

)

#include <api.h>

Create a Mutex object.

Returns

The Mutex handle on success, or NULL on failure.

Referenced by ocilib::Mutex::Create().

OCI_MutexFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_MutexFree

(

OCI_Mutex *

mutex

)

#include <api.h>

Destroy a mutex object.

Parameters

mutex

- Mutex handle

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Mutex::Destroy().

OCI_MutexAcquire()

OCI_SYM_PUBLIC boolean OCI_API OCI_MutexAcquire

(

OCI_Mutex *

mutex

)

#include <api.h>

Acquire a mutex lock.

Parameters

mutex

- Mutex handle

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Mutex::Acquire().

OCI_MutexRelease()

OCI_SYM_PUBLIC boolean OCI_API OCI_MutexRelease

(

OCI_Mutex *

mutex

)

#include <api.h>

Release a mutex lock.

Parameters

mutex

- Mutex handle

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Mutex::Release().

OCI_ThreadCreate()

OCI_SYM_PUBLIC OCI_Thread *OCI_API OCI_ThreadCreate

(

void

)

#include <api.h>

Create a Thread object.

Returns

The Thread handle on success, or NULL on failure.

Referenced by ocilib::Thread::Create().

OCI_ThreadFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_ThreadFree

(

OCI_Thread *

thread

)

#include <api.h>

Destroy a thread object.

Parameters

thread

- Thread handle

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Thread::Destroy().

OCI_ThreadRun()

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

#include <api.h>

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.

Referenced by ocilib::Thread::Run().

OCI_ThreadJoin()

OCI_SYM_PUBLIC boolean OCI_API OCI_ThreadJoin

(

OCI_Thread *

thread

)

#include <api.h>

Join the given thread.

Parameters

thread

- Thread handle

Note

This function waits for the given thread to finish.

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Thread::Join().

OCI_ThreadKeyCreate()

OCI_SYM_PUBLIC boolean OCI_API OCI_ThreadKeyCreate	(	const otext *	name,
		POCI_THREADKEYDEST	destfunc
	)

#include <api.h>

Create a thread key object.

Parameters

name	- Thread key name
destfunc	- Thread key value destructor function

Note

Parameter destfunc is optional. It is 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.

Referenced by ocilib::ThreadKey::Create().

OCI_ThreadKeySetValue()

OCI_SYM_PUBLIC boolean OCI_API OCI_ThreadKeySetValue	(	const otext *	name,
		void *	value
	)

#include <api.h>

Set a thread key value.

Parameters

name	- Thread key name
value	- User value to set

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::ThreadKey::SetValue().

OCI_ThreadKeyGetValue()

OCI_SYM_PUBLIC void *OCI_API OCI_ThreadKeyGetValue

(

const otext *

name

)

#include <api.h>

Get a thread key value.

Parameters

name	- Thread key name

Returns

The thread key value on success, or NULL on failure.

Referenced by ocilib::ThreadKey::GetValue().