OpenRM - RM Library (rmthread.c)

## Index of OpenRM - RM Library

     RMenum rmThreadCreate(RMthread *threadID,
    	               void * (*threadFunc)(void *),
    	               void *args)

     RMthread *threadID - a handle to an RMthread object (modified).
     void * (*threadFunc)(void *) - a handle to a function that will be
        executed by the new thread (input).
     void *args - arguments to the threadFunc, cast to a void *.

Use this routine to create a new execution thread. rmThreadCreate is a threads-abstraction layer that creates new execution threads in both Unix and Win32 environments. The Unix version is built using POSIX threads - for more information, see pthread_create(3). On Win32, see the MSDN documentation for _beginthread().

The new thread is detached, and begins immediate execution of the code contained in the routine "threadFunc". Arguments to the threadFunc may be passed through the parameter "args." Typically, args are packaged into a struct, and the handle to the struct is cast to a void *. The threadFunc then performs an inverse cast of the void *args to a struct * to gain access to the arguments.

rmThreadCreate only creates a detached thread. Any synchronization must be performed by the application using the appropriate constructs. RMmutex's can be used (both Win32 and Unix) to implement synchronization. Alternatively, developers who have specialized knowledge of OS-specific features (e.g., semaphores, condition variables, etc) may use those constructs.

Upon success, this routine will return RM_CHILL, and the RMthread *threadID is modified to contain thread-specific identification information. Upon failure, an error message is printed, and a RM_WHACKED is returned.

librm library source file: rmthread.c

     RMenum rmThreadJoin(RMthread *threadID,
    	             void **threadReturn)

     RMthread *threadID - a handle to an RMthread object (input).
     void **threadReturn - a handle to a void * (modified).

"Thread joining" means "wait for the thread to finish." Use rmThreadJoin to wait for completion of a thread. Upon success, this routine returns RM_CHILL, indicating the thread in question has completed. Upon failure, an error message is printed, and RM_WHACKED is returned (Unix only).

NOTE: this function is a no-op on Win32, as there is no equivalent thread join routine in Win32. Developers must use explicit synchronization mechanisms on Win32 to coordinate signaling of completion between app and detached threads. The RMmutex will work nicely for that purpose.

librm library source file: rmthread.c

     RMmutex * rmMutexNew(RMenum initLockState)

     RMenum initLockState - an RMenum value (input) specifying the
     initial state of the RMmutex returned to the caller.

Creates an initialized RMmutex object, and returns the handle of the new RMmutex object to the caller upon success, or NULL upon failure. The initial value of the RMmutex is set to the value specified by the input parameter initLockState.

Valid values for initLockState are RM_MUTEX_LOCK or RM_MUTEX_UNLOCK.

The RMmutex object is a synchronization mechanism that can be used to control access to critical resources, and may be used across multiple threads or processes. A full description of mutex usage and theory is beyond the scope of this document. Please refer to literature for more details (eg, Programming With Posix Threads, by Butenhof, Addison-Wesley).

Attempting to access (or lock) an already locked mutex using rmMutexLock() will cause the caller to block until the mutex is released (unlocked). Attempting to unlock and already-unlocked mutex using rmMutexUnlock() will have no effect. Callers can use check the status of a mutex with rmMutexTryLock(), which is non-blocking.

OpenRM RMmutex objects (in Linux) use the "error checking" kind of mutex - which means attempts to lock a mutex already owned and locked by the calling thread will not result in multiple locks (like a semaphore). Instead, an error is reported. In general, OpenRM applications developers should use lots of programming discipline to avoid cases in which code will apply multiple locks to a given mutex.

OpenRM mutex objects are intended to behave similarly in both Unix and Win32 environments.

librm library source file: rmthread.c

     RMenum rmMutexDelete(RMmutex *toDelete)

     RMmutex * toDelete - a handle to an RMmutex object (modified).

Releases resources associated with an RMmutex object. Callers should take care to ensure the RMmutex object is unlocked prior to calling rmMutexDelete().

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

The RMmutex object is a synchronization mechanism that can be used to control access to critical resources, and may be used across multiple threads or processes. A full description of mutex usage and theory is beyond the scope of this document. Please refer to literature for more details (eg, Programming With Posix Threads, by Butenhof, Addison-Wesley).

Attempting to access (or lock) an already locked mutex using rmMutexLock() will cause the caller to block until the mutex is released (unlocked). Attempting to unlock and already-unlocked mutex using rmMutexUnlock() will have no effect. Callers can use check the status of a mutex with rmMutexTryLock(), which is non-blocking.

OpenRM RMmutex objects (in Linux) use the "error checking" kind of mutex - which means attempts to lock a mutex already owned and locked by the calling thread will not result in multiple locks (like a semaphore). Instead, an error is reported. In general, OpenRM applications developers should use lots of programming discipline to avoid cases in which code will apply multiple locks to a given mutex.

OpenRM mutex objects are intended to behave similarly in both Unix and Win32 environments.

librm library source file: rmthread.c

     RMenum rmMutexLock(RMmutex *toLock)

     RMmutex * toLock - a handle to an RMmutex object (modified).

Performs a blocking wait until the RMmutex object toLock is unlocked, then will apply a lock and return RM_CHILL to the caller. A return status of RM_WHACKED indicates an error of some type. When an error is detected, this routine will call perror() (on Unix) or its equivalent (on Win32) to report the cause of the error.

The RMmutex object is a synchronization mechanism that can be used to control access to critical resources, and may be used across multiple threads or processes. A full description of mutex usage and theory is beyond the scope of this document. Please refer to literature for more details (eg, Programming With Posix Threads, by Butenhof, Addison-Wesley).

Attempting to access (or lock) an already locked mutex using rmMutexLock() will cause the caller to block until the mutex is released (unlocked). Attempting to unlock and already-unlocked mutex using rmMutexUnlock() will have no effect. Callers can use check the status of a mutex with rmMutexTryLock(), which is non-blocking.

OpenRM RMmutex objects (in Linux) use the "error checking" kind of mutex - which means attempts to lock a mutex already owned and locked by the calling thread will not result in multiple locks (like a semaphore). Instead, an error is reported. In general, OpenRM applications developers should use lots of programming discipline to avoid cases in which code will apply multiple locks to a given mutex.

OpenRM mutex objects are intended to behave similarly in both Unix and Win32 environments.

librm library source file: rmthread.c

     RMenum rmMutexUnlock(RMmutex *toUnlock)

     RMmutex * toUnlock - a handle to an RMmutex object (modified).

Unlocks an RMmutex object. This call is non-blocking. Upon success, RM_CHILL is returned to the caller. Upon failure, RM_WHACKED is returned. When an error is detected, this routine will call perror() (on Unix) or its equivalent (on Win32) to report the cause of the error.

The RMmutex object is a synchronization mechanism that can be used to control access to critical resources, and may be used across multiple threads or processes. A full description of mutex usage and theory is beyond the scope of this document. Please refer to literature for more details (eg, Programming With Posix Threads, by Butenhof, Addison-Wesley).

Attempting to access (or lock) an already locked mutex using rmMutexLock() will cause the caller to block until the mutex is released (unlocked). Attempting to unlock and already-unlocked mutex using rmMutexUnlock() will have no effect. Callers can use check the status of a mutex with rmMutexTryLock(), which is non-blocking.

OpenRM RMmutex objects (in Linux) use the "error checking" kind of mutex - which means attempts to lock a mutex already owned and locked by the calling thread will not result in multiple locks (like a semaphore). Instead, an error is reported. In general, OpenRM applications developers should use lots of programming discipline to avoid cases in which code will apply multiple locks to a given mutex.

OpenRM mutex objects are intended to behave similarly in both Unix and Win32 environments.

librm library source file: rmthread.c

     RMenum rmMutexTryLock(RMmutex *toLock)

     RMmutex * toLock - a handle to an RMmutex object (modified).

Attempts to lock an RMmutex object - this call is non-blocking.

If the RMmutex object is locked, a value of RM_MUTEX_BUSY is returned to the caller, and the input RMmutex object remains unmodified.

If the RMmutex was unlocked, this routine will lock it, and return RM_MUTEX_LOCK to the caller.

The RMmutex object is a synchronization mechanism that can be used to control access to critical resources, and may be used across multiple threads or processes. A full description of mutex usage and theory is beyond the scope of this document. Please refer to literature for more details (eg, Programming With Posix Threads, by Butenhof, Addison-Wesley).

Attempting to access (or lock) an already locked mutex using rmMutexLock() will cause the caller to block until the mutex is released (unlocked). Attempting to unlock and already-unlocked mutex using rmMutexUnlock() will have no effect. Callers can use check the status of a mutex with rmMutexTryLock(), which is non-blocking.

OpenRM RMmutex objects (in Linux) use the "error checking" kind of mutex - which means attempts to lock a mutex already owned and locked by the calling thread will not result in multiple locks (like a semaphore). Instead, an error is reported. In general, OpenRM applications developers should use lots of programming discipline to avoid cases in which code will apply multiple locks to a given mutex.

OpenRM mutex objects are intended to behave similarly in both Unix and Win32 environments.

librm library source file: rmthread.c