This section describes the thread management functions.
Table 16-9 Thread Management functions
Function | Purpose |
---|---|
Closes a thread handle |
|
Creates a new thread |
|
Retrieves the OCIThreadHandle of the thread in which it is called |
|
Destroys and deallocates the thread handle |
|
Allocates and initializes the thread handle |
|
Destroys and deallocates a thread id |
|
Retrieves the |
|
Allocates and initializes the thread id |
|
Determines whether or not a given |
|
Determines whether or not two |
|
Sets one |
|
Sets the NULL thread ID to a given |
|
Initializes OCIThread context |
|
Tells the caller whether the application is running in a multithreaded environment or a single-threaded environment |
|
Allows the calling thread to join with another thread |
|
Destroy and deallocate the key pointed to by |
|
Gets the calling threads current value for a key |
|
Creates a key |
|
Sets the calling threads value for a key |
|
Acquires a mutex for the thread in which it is called |
|
Destroys and deallocate a mutex |
|
Allocates and initializes a mutex |
|
Releases a mutex |
|
Performs OCIThread process initialization |
|
Releases the OCIThread context |
Closes a thread handle.
sword OCIThreadClose ( dvoid *hndl, OCIError *err, OCIThreadHandle *tHnd );
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Diagnostic information can be obtained by calling OCIErrorGet()
.
The OCIThread thread handle to close.
tHnd
should be initialized by OCIThreadHndInit()
. Both thread handle and the thread ID that was returned by the same call to OCIThreadCreate()
are invalid after the call to OCIThreadClose()
.
Creates a new thread.
sword OCIThreadCreate ( dvoid *hndl, OCIError *err, void (*start) (dvoid dvoid *arg, OCIThreadId *tid, OCIThreadHandle *tHnd );
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Diagnostic information can be obtained by calling OCIErrorGet()
.
The function in which the new thread should begin execution.
The argument to give the function pointed to by start
.
If not NULL, gets the ID for the new thread.
If not NULL, gets the handle for the new thread.
The new thread starts by executing a call to the function pointed to by start
with the argument given by arg
. When that function returns, the new thread will terminate. The function should not return a value and should accept one parameter, a dvoid
. The call to OCIThreadCreate()
must be matched by a call to OCIThreadClose()
if and only if tHnd
is non-NULL.
If tHnd
is NULL, a thread ID placed in *tid
will not be valid in the calling thread because the timing of the spawned threads termination is unknown.
tid
should be initialized by OCIThreadIdInit()
and tHnd
should be initialized by OCIThreadHndInit()
.
OCIThreadClose(), OCIThreadIdInit(), OCIThreadHndInit()
Retrieves the OCIThreadHandle
of the thread in which it is called.
sword OCIThreadHandleGet ( dvoid *hndl, OCIError *err, OCIThreadHandle *tHnd );
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Diagnostic information can be obtained by calling OCIErrorGet()
.
If not NULL, the location to place the thread handle for the thread.
tHnd
should be initialized by OCIThreadHndInit()
.
The thread handle tHnd
retrieved by this function must be closed with OCIThreadClose()
and destroyed by OCIThreadHndDestroy()
after it is used.
OCIThreadHndDestroy(), OCIThreadHndInit()
Destroys and deallocates the thread handle.
sword OCIThreadHndDestroy ( dvoid *hndl, OCIError *err, OCIThreadHandle **thnd );
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Diagnostic information can be obtained by calling OCIErrorGet()
.
The address of pointer to the thread handle to destroy.
thnd
should be initialized by OCIThreadHndInit()
.
OCIThreadHandleGet(), OCIThreadHndInit()
Allocates and initializes the thread handle.
sword OCIThreadHndInit ( dvoid *hndl, OCIError *err, OCIThreadHandle **thnd );
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Diagnostic information can be obtained by calling OCIErrorGet()
.
The address of pointer to the thread handle to initialize.
OCIThreadHandleGet(), OCIThreadHndDestroy()
Destroys and deallocates a thread Id.
sword OCIThreadIdDestroy (dvoid *hndl, OCIError *err, OCIThreadId **tid );
The OCI environment or user session handle.
The OCI error handle. If there is an error and OCI_ERROR is returned, the error is recorded in err
and diagnostic information can be obtained by calling OCIErrorGet()
.
Pointer to the thread ID to destroy.
tid
should be initialized by OCIThreadIdInit()
.
OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet(), OCIThreadIdSetNull()
Retrieves the OCIThreadId
of the thread in which it is called.
sword OCIThreadIdGet ( dvoid *hndl, OCIError *err, OCIThreadId *tid );
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Diagnostic information can be obtained by calling OCIErrorGet()
.
This should point to the location in which to place the ID of the calling thread.
tid
should be initialized by OCIThreadIdInit()
. When OCIThread is used in a single-threaded environment, OCIThreadIdGet()
will always place the same value in the location pointed to by tid
. The exact value itself is not important. The important thing is that it is not the same as the NULL thread ID and that it is always the same value.
OCIThreadIdDestroy(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet(), OCIThreadIdSetNull()
Allocate and initialize the thread Id tid
.
sword OCIThreadIdInit ( dvoid *hndl, OCIError *err, OCIThreadId **tid );
The OCI environment or user session handle.
The OCI error handle. If there is an error and OCI_ERROR
is returned, the error is recorded in err
and diagnostic information can be obtained by calling OCIErrorGet()
.
Pointer to the thread ID to initialize.
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet(), OCIThreadIdSetNull()
Determines whether or not a given OCIThreadId
is the NULL
thread Id.
sword OCIThreadIdNull ( dvoid *hndl, OCIError *err, OCIThreadId *tid, boolean *result );
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Diagnostic information can be obtained by calling OCIErrorGet()
.
Pointer to the OCIThreadId
to check.
Pointer to the result.
If tid
is the NULL
thread ID, result
is set to TRUE
. Otherwise, result
is set to FALSE
. tid
should be initialized by OCIThreadIdInit()
.
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdSame(), OCIThreadIdSet(), OCIThreadIdSetNull()
Determines whether or not two OCIThreadId
s represent the same thread.
sword OCIThreadIdSame ( dvoid *hndl, OCIError *err, OCIThreadId *tid1, OCIThreadId *tid2, boolean *result );
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Diagnostic information can be obtained by calling OCIErrorGet()
.
Pointer to the first OCIThreadId
.
Pointer to the second OCIThreadId
.
Pointer to the result.
If tid1
and tid2
represent the same thread, result
is set to TRUE
. Otherwise, result
is set to FALSE
. result
is set to TRUE
if both tid1
and tid2
are the NULL
thread ID. ti1d
and tid2
should be initialized by OCIThreadIdInit()
.
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSet(), OCIThreadIdSetNull()
Sets one OCIThreadId
to another.
sword OCIThreadIdSet ( dvoid *hndl, OCIError *err, OCIThreadId *tidDest, OCIThreadId *tidSrc );
The OCI environment or user session handle.
The OCI error handle. If there is an error and OCI_ERROR
is returned, the error is recorded in err
and diagnostic information can be obtained by calling OCIErrorGet()
.
This should point to the location of the OCIThreadId
to be set to.
This should point to the OCIThreadId
to set from.
tid
should be initialized by OCIThreadIdInit()
.
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSetNull()
Sets the NULL
thread ID to a given OCIThreadId
.
sword OCIThreadIdSetNull ( dvoid *hndl, OCIError *err, OCIThreadId *tid );
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Diagnostic information can be obtained by calling OCIErrorGet()
.
This should point to the OCIThreadId
in which to put the NULL thread Id.
tid
should be initialized by OCIThreadIdInit()
.
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet()
Initializes the OCIThread context.
sword OCIThreadInit ( dvoid *hndl, OCIError *err );
The OCI environment or user session handle.
The OCI error handle. If there is an error and OCI_ERROR
is returned, the error is recorded in err
and diagnostic information can be obtained by calling OCIErrorGet()
.
It is illegal for OCIThread clients to try an examine the memory pointed to by the returned pointer. It is safe to make concurrent calls to OCIThreadInit()
. Unlike OCIThreadProcessInit()
, there is no need to have a first call that occurs before all the others.
The first time OCIThreadInit()
is called, it initializes the OCI Thread context. It also saves a pointer to the context in some system dependent manner. Subsequent calls to OCIThreadInit()
will return the same context.
Each call to OCIThreadInit()
must eventually be matched by a call to OCIThreadTerm()
.
Tells the caller whether the application is running in a multithreaded environment or a single-threaded environment.
boolean OCIThreadIsMulti ( );
TRUE
if the environment is multithreaded;
FALSE
if the environment is single-threaded.
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet()
Allows the calling thread to join with another thread.
sword OCIThreadJoin ( dvoid *hndl, OCIError *err, OCIThreadHandle *tHnd );
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Diagnostic information can be obtained by calling OCIErrorGet()
.
The OCIThreadHandle
of the thread to join with.
This function blocks the caller until the specified thread terminates.
tHnd
should be initialized by OCIThreadHndInit()
. The result of multiple threads all trying to join with the same thread is undefined.
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet()
Destroy and deallocate the key pointed to by key
.
sword OCIThreadKeyDestroy ( dvoid *hndl, OCIError *err, OCIThreadKey **key );
The OCI environment or user session handle.
The OCI error handle. If there is an error and OCI_ERROR
is returned, the error is recorded in err
and diagnostic information can be obtained by calling OCIErrorGet()
.
The OCIThreadKey
in which to destroy the key.
This is different from the destructor function callback passed to the key create routine. This new destroy function OCIThreadKeyDestroy()
is used to terminate any resources OCI THREAD acquired when it created key
. The OCIThreadKeyDestFunc
callback of OCIThreadKeyInit()
is a key VALUE destructor; it does in no way operate on the key itself.
This must be called once the user has finished using the key. Not calling the key destroy function may result in memory leaks.
OCIThreadKeyGet(), OCIThreadKeyInit(), OCIThreadKeySet()
Gets the calling threads current value for a key.
sword OCIThreadKeyGet ( dvoid *hndl, OCIError *err, OCIThreadKey *key, dvoid **pValue );
The OCI environment or user session handle.
The OCI error handle. If there is an error and OCI_ERROR
is returned, the error is recorded in err
and diagnostic information can be obtained by calling OCIErrorGet()
.
The key.
The location in which to place the thread-specific key value.
It is illegal to use this function on a key that has not been created using OCIThreadKeyInit()
.
If the calling thread has not yet assigned a value to the key, NULL
is placed in the location pointed to by pValue
.
OCIThreadKeyDestroy(), OCIThreadKeyInit(), OCIThreadKeySet()
Creates a key.
sword OCIThreadKeyInit (dvoid *hndl, OCIError *err, OCIThreadKey **key, OCIThreadKeyDestFunc destFn );
The OCI environment or user session handle.
The OCI error handle. If there is an error and OCI_ERROR
is returned, the error is recorded in err
and diagnostic information can be obtained by calling OCIErrorGet()
.
The OCIThreadKey
in which to create the new key.
The destructor for the key. NULL
is permitted.
Each call to this routine allocate and generates a new key that is distinct from all other keys. After this function executes successfully, a pointer to an allocated and initialized key is return. That key can be used with OCIThreadKeyGet()
and OCIThreadKeySet()
. The initial value of the key will be NULL
for all threads.
It is illegal for this function to be called more than once with the same value for the key
parameter.
If the destFn
parameter is not NULL
, the routine pointed to by destFn
will be called whenever a thread that has a non-NULL
value for the key terminates. The routine will be called with one parameter. The parameter will be the keys value for the thread at the time at which the thread terminated. If the key does not need a destructor function, pass NULL
for destFn
.
OCIThreadKeyDestroy(), OCIThreadKeyGet(), OCIThreadKeySet()
Sets the calling threads value for a key.
sword OCIThreadKeySet ( dvoid *hndl, OCIError *err, OCIThreadKey *key, dvoid *value );
The OCI environment or user session handle.
The OCI error handle. If there is an error and OCI_ERROR
is returned, the error is recorded in err
and diagnostic information can be obtained by calling OCIErrorGet()
.
The key.
The thread-specific value to set in the key.
It is illegal to use this function on a key that has not been created using OCIThreadKeyInit()
.
OCIThreadKeyDestroy(), OCIThreadKeyGet(), OCIThreadKeyInit()
Acquires a mutex for the thread in which it is called.
sword OCIThreadMutexAcquire ( dvoid *hndl, OCIError *err, OCIThreadMutex *mutex );
The OCI environment or user session handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR
. Diagnostic information can be obtained by calling OCIErrorGet()
.
The mutex to acquire.
If the mutex is held by another thread, the calling thread is blocked until it can acquire the mutex.
It is illegal to attempt to acquire an uninitialized mutex.
This functions behavior is undefined if it is used by a thread to acquire a mutex that is already held by that thread.
OCIThreadMutexDestroy(), OCIThreadMutexInit(), OCIThreadMutexRelease()
Destroys and deallocate a mutex.
sword OCIThreadMutexDestroy ( dvoid *hndl, OCIError *err, OCIThreadMutex **mutex );
The OCI environment or user session handle.
The OCI error handle. If there is an error and OCI_ERROR
is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet()
.
The mutex to destroy.
Each mutex must be destroyed once it is no longer needed.
It is not legal to destroy a mutex that is uninitialized or is currently held by a thread. The destruction of a mutex must not occur concurrently with any other operations on the mutex. A mutex must not be used after it has been destroyed.
OCIThreadMutexAcquire(), OCIThreadMutexInit(), OCIThreadMutexRelease()
Allocates and initializes a mutex.
sword OCIThreadMutexInit ( dvoid *hndl, OCIError *err, OCIThreadMutex **mutex );
The OCI environment or user session handle.
The OCI error handle. If there is an error and OCI_ERROR
is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet()
.
The mutex to initialize.
All mutexes must be initialized prior to use.
Multiple threads must not initialize the same mutex simultaneously. Also, a mutex must not be reinitialized until it has been destroyed (see OCIThreadMutexDestroy()
).
OCIThreadMutexDestroy(), OCIThreadMutexAcquire(), OCIThreadMutexRelease()
Releases a mutex.
sword OCIThreadMutexRelease ( dvoid *hndl, OCIError *err, OCIThreadMutex *mutex );
The OCI environment or user session handle.
The OCI error handle. If there is an error and OCI_ERROR
is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet()
.
The mutex to release.
If there are any threads blocked on the mutex, one of them will acquire it and become unblocked.
It is illegal to attempt to release an uninitialized mutex. It is also illegal for a thread to release a mutex that it does not hold.
OCIThreadMutexDestroy(), OCIThreadMutexInit(), OCIThreadMutexAcquire()
Performs OCIThread process initialization.
void OCIThreadProcessInit ( );
Whether or not this function needs to be called depends on how OCI Thread is going to be used.
In a single-threaded application, calling this function is optional. If it is called at all, the first call to it must occur before calls to any other OCIThread functions. Subsequent calls can be made without restriction; they will not have any effect.
In a multithreaded application, this function must be called. The first call to it must occur strictly before any other OCIThread calls; that is, no other calls to OCIThread functions (including other calls to this one) can be concurrent with the first call.
Subsequent calls to this function can be made without restriction; they will not have any effect.
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet()
Releases the OCIThread context.
sword OCIThreadTerm ( dvoid *hndl, OCIError *err );
The OCI environment or user session handle.
The OCI error handle. If there is an error and OCI_ERROR
is returned, the error is recorded in err and diagnostic information can be obtained by calling OCIErrorGet()
.
This function should be called exactly once for each call made to OCIThreadInit()
.
It is safe to make concurrent calls to OCIThreadTerm()
. OCIThreadTerm()
will not do anything until it has been called as many times as OCIThreadInit()
has been called. When that happens, it terminates the OCIThread layer and frees the memory allocated for the context. Once this happens, the context should not be re-used. It will be necessary to obtain a new one by calling OCIThreadInit()
.