CMPI 2.1.0 API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Typedefs | Variables
OS Encapsulation Services - POSIX-conformant Threads (Subclause 9.14)

Typedefs

typedef CMPI_THREAD_RETURN(CMPI_THREAD_CDECLCMPIThreadFunc )(void *parm)
 A function pointer type for a POSIX thread function. More...
 
typedef void(* CMPIThreadOnceFunc )(void)
 A function pointer type for a function that is called once in a POSIX thread. More...
 
typedef void(* CMPIThreadKeyCleanupFunc )(void *key)
 A function pointer type for a POSIX thread key cleanup function. More...
 

Variables

CMPI_THREAD_TYPE(* CMPIBrokerExtFT::newThread )(CMPIThreadFunc start, void *parm, int detached)
 Start a new thread, using POSIX threading semantics. More...
 
int(* CMPIBrokerExtFT::joinThread )(CMPI_THREAD_TYPE thread, CMPI_THREAD_RETURN *retval)
 Wait until the specified thread ends, using POSIX threading semantics. More...
 
int(* CMPIBrokerExtFT::exitThread )(CMPI_THREAD_RETURN return_code)
 Cause current thread to exit with the passed-in return code, using POSIX threading semantics. More...
 
int(* CMPIBrokerExtFT::cancelThread )(CMPI_THREAD_TYPE thread)
 Cancel a running thread, using POSIX threading semantics. More...
 
int(* CMPIBrokerExtFT::threadSleep )(CMPIUint32 msec)
 Suspend execution of current thread for a specified duration. More...
 
int(* CMPIBrokerExtFT::threadOnce )(int *once, CMPIThreadOnceFunc function)
 Call a function once for a given once-object. More...
 
int(* CMPIBrokerExtFT::createThreadKey )(CMPI_THREAD_KEY_TYPE *key, CMPIThreadKeyCleanupFunc cleanup)
 Create a POSIX threading-conformant thread key for accessing the thread local store. More...
 
int(* CMPIBrokerExtFT::destroyThreadKey )(CMPI_THREAD_KEY_TYPE key)
 Destroy a POSIX threading-conformant thread key for accessing the thread local store. More...
 
void *(* CMPIBrokerExtFT::getThreadSpecific )(CMPI_THREAD_KEY_TYPE key)
 Get a data pointer from the thread local store using a POSIX threading-conformant thread key. More...
 
int(* CMPIBrokerExtFT::setThreadSpecific )(CMPI_THREAD_KEY_TYPE key, void *value)
 Set a data pointer in the thread local store using a POSIX threading-conformant thread key. More...
 

Detailed Description

Typedef Documentation

typedef CMPI_THREAD_RETURN(CMPI_THREAD_CDECL * CMPIThreadFunc)(void *parm)

A function pointer type for a POSIX thread function.

Such a function pointer is passed to CMPIBrokerExtFT.newThread().

Parameters
parmA pointer to arbitrary data, which was passed to CMPIBrokerExtFT.newThread().
Returns
The return value of the thread function. This value can be retrieved by the caller of CMPIBrokerExtFT.joinThread().

For more details on such functions, see the pthread_create() function defined in IEEE 1003.1.

typedef void(* CMPIThreadOnceFunc)(void)

A function pointer type for a function that is called once in a POSIX thread.

Such a function pointer is passed to CMPIBrokerExtFT.threadOnce().

Returns
None.

For more details on such functions, see the pthread_once() function defined in IEEE 1003.1.

typedef void(* CMPIThreadKeyCleanupFunc)(void *key)

A function pointer type for a POSIX thread key cleanup function.

Such a function pointer is passed to CMPIBrokerExtFT.createThreadKey().

Parameters
keyA pointer to the previous key value before cleanup.
Returns
None.

For more details on such functions, see the pthread_key_create() function defined in IEEE 1003.1.

Variable Documentation

CMPI_THREAD_TYPE(* CMPIBrokerExtFT::newThread)(CMPIThreadFunc start, void *parm, int detached)

Start a new thread, using POSIX threading semantics.

CMPIBrokerExtFT.newThread() starts a new thread, using POSIX threading semantics.

Creating a thread using CMPIBrokerExtFT.newThread() does not inform the MB that the new thread will begin using MB functions. Thus, CMPIBrokerFT.attachThread() must be called by the new thread before it uses MB functions.

Parameters
startPoints to the function to be started as a thread. For details, see type CMPIThreadFunc.
parmPoints to argument(s) to be passed to that function.
detachedIf not zero, defines that the new thread should run in detached mode. In detached mode, termination of the thread that called this function does not cause the new thread to be canceled. See IEEE 1003.1 for details on detached mode.
Returns

If successful, the handle of the started thread will be returned.

If not successful, NULL will be returned.

Errors
For historical reasons, no additional error information is passed back.
Convenience Function
None.
Capabilities:
Part of the OS Encapsulation Services capability.
Requirement Change:
Required to be supported since CMPI 2.0.
Todo:
TODO_KS Karl to test the new function types in actual code, particularly with MSVC compiler: CMPIThreadFunc, CMPIThreadOnceFunc, CMPIThreadKeyCleanupFunc.
int(* CMPIBrokerExtFT::joinThread)(CMPI_THREAD_TYPE thread, CMPI_THREAD_RETURN *retval)

Wait until the specified thread ends, using POSIX threading semantics.

CMPIBrokerExtFT.joinThread() suspends the current thread to wait until the specified thread ends, using POSIX threading semantics.

Parameters
threadHandle of the thread to wait for.
retvalPoints to the return value of the thread. On successful completion, the return value of the thread will be stored in this location.
Returns

If successful, zero will be returned.

If not successful, a non-zero error code will be returned.

Errors
Error codes are defined in errno.h, specifically for the pthread_join() function; both are defined in IEEE 1003.1.
Convenience Function
None.
Capabilities:
Part of the OS Encapsulation Services capability.
Requirement Change:
Required to be supported since CMPI 2.0.
int(* CMPIBrokerExtFT::exitThread)(CMPI_THREAD_RETURN return_code)

Cause current thread to exit with the passed-in return code, using POSIX threading semantics.

CMPIBrokerExtFT.exitThread() causes the current thread to exit with the passed-in return code, using POSIX threading semantics.

The current thread can also exit by simply returning from its thread function; the purpose of the CMPIBrokerExtFT.exitThread() function is to make premature returns more convenient.

Parameters
return_codeThe return code that should be used for the thread.
Returns
The function never returns, regardless of whether it is successful or encounters errors.
Errors
None; the function never returns.
Convenience Function
None.
Capabilities:
Part of the OS Encapsulation Services capability.
Requirement Change:
Required to be supported since CMPI 2.0.
int(* CMPIBrokerExtFT::cancelThread)(CMPI_THREAD_TYPE thread)

Cancel a running thread, using POSIX threading semantics.

CMPIBrokerExtFT.cancelThread() cancels the thread identified by thread, using POSIX threading semantics.

Parameters
threadHandle of the thread to be canceled.
Returns

If successful, zero will be returned.

If not successful, a non-zero error code will be returned.

Errors

Error codes are defined in errno.h, specifically for the pthread_cancel() function; both are defined in IEEE 1003.1.

The pthread_cancel() function does not define any error codes in IEEE 1003.1. Some POSIX implementations use the following error code for that function:

  • ESRCH -The specified thread could not be found.
Convenience Function
None.
Capabilities:
Part of the OS Encapsulation Services capability.
Requirement Change:
Required to be supported since CMPI 2.0.
int(* CMPIBrokerExtFT::threadSleep)(CMPIUint32 msec)

Suspend execution of current thread for a specified duration.

CMPIBrokerExtFT.threadSleep() suspends the execution of the current thread for a specified duration.

Parameters
msecSuspend duration in milliseconds.
Returns

If successful, zero will be returned.

If not successful, a non-zero error code will be returned.

Errors
Error codes are defined in errno.h, defined in IEEE 1003.1.
Convenience Function
None.
Capabilities:
Part of the OS Encapsulation Services capability.
Requirement Change:
Required to be supported since CMPI 2.0.
int(* CMPIBrokerExtFT::threadOnce)(int *once, CMPIThreadOnceFunc function)

Call a function once for a given once-object.

CMPIBrokerExtFT.threadOnce() calls a function once for a given once-object. The once-object is an integer that initially shall have a value of zero. The first call to CMPIBrokerExtFT.threadOnce() with an initialized once-object will call the specified function. On return from CMPIBrokerExtFT.threadOnce(), it is guaranteed that the specified function has completed, and that the once-object has been updated to indicate that. Subsequent calls to CMPIBrokerExtFT.threadOnce() by any thread within the process with that once-object will not call the specified function.

Parameters
[in,out]oncePoints to the once-object. The value of the once-object controls whether the specified function has yet to be called. The once-object may be located in thread-specific memory (that is, each thread has its own separate copy), or in memory that is accessible to all threads of the process. The function will behave in a thread-safe way. The once-object shall be initialized to zero before the first call to the CMPIBrokerExtFT.threadOnce() function.
functionPoints to the function to be invoked. For details, see type CMPIThreadOnceFunc.
Returns

If successful, zero will be returned.

If not successful, a non-zero error code will be returned.

Errors
Error codes are defined in errno.h, specifically for the pthread_once() function; both are defined in IEEE 1003.1.
Convenience Function
None.
Capabilities:
Part of the OS Encapsulation Services capability.
Requirement Change:
Required to be supported since CMPI 2.0.
int(* CMPIBrokerExtFT::createThreadKey)(CMPI_THREAD_KEY_TYPE *key, CMPIThreadKeyCleanupFunc cleanup)

Create a POSIX threading-conformant thread key for accessing the thread local store.

CMPIBrokerExtFT.createThreadKey() creates a POSIX threading-conformant thread key that can be used as a key to access the thread local store.

Parameters
[out]keyPoints to the thread key to be returned.
cleanupPoints to the function to be invoked during thread local store cleanup. For details, see type CMPIThreadKeyCleanupFunc.
Returns

If successful, zero will be returned.

If not successful, a non-zero error code will be returned.

Errors
Error codes are defined in errno.h, specifically for the pthread_key_create() function; both are defined in IEEE 1003.1.
Convenience Function
None.
Capabilities:
Part of the OS Encapsulation Services capability.
Requirement Change:
Required to be supported since CMPI 2.0.
int(* CMPIBrokerExtFT::destroyThreadKey)(CMPI_THREAD_KEY_TYPE key)

Destroy a POSIX threading-conformant thread key for accessing the thread local store.

CMPIBrokerExtFT.destroyThreadKey() destroys a POSIX threading-conformant thread key for accessing the thread local store.

Parameters
keyThread key to be destroyed.
Returns

If successful, zero will be returned.

If not successful, a non-zero error code will be returned.

Errors
Error codes are defined in errno.h, specifically for the pthread_key_delete() function; both are defined in IEEE 1003.1.
Convenience Function
None.
Capabilities:
Part of the OS Encapsulation Services capability.
Requirement Change:
Required to be supported since CMPI 2.0.
void*(* CMPIBrokerExtFT::getThreadSpecific)(CMPI_THREAD_KEY_TYPE key)

Get a data pointer from the thread local store using a POSIX threading-conformant thread key.

CMPIBrokerExtFT.getThreadSpecific() gets a data pointer from the thread local store using a POSIX threading-conformant thread key.

Parameters
keyThread key to be used to retrieve the data pointer.
Returns

If successful, the data pointer will be returned.

If not successful, NULL will be returned.

Errors
For historical reasons, no additional error information is passed back.
Convenience Function
None.
Capabilities:
Part of the OS Encapsulation Services capability.
Requirement Change:
Required to be supported since CMPI 2.0.
int(* CMPIBrokerExtFT::setThreadSpecific)(CMPI_THREAD_KEY_TYPE key, void *value)

Set a data pointer in the thread local store using a POSIX threading-conformant thread key.

CMPIBrokerExtFT.setThreadSpecific() sets a data pointer in the thread local store using a POSIX threading-conformant thread key.

Parameters
keyThread key to be used.
valueData pointer that is stored in the thread local store.
Returns

If successful, zero will be returned.

If not successful, a non-zero error code will be returned.

Errors
Error codes are defined in errno.h, specifically for the pthread_setspecific() function; both are defined in IEEE 1003.1.
Convenience Function
None.
Capabilities:
Part of the OS Encapsulation Services capability.
Requirement Change:
Required to be supported since CMPI 2.0.