Sophie: libopenrm1-1.5.2-2mdv2007.0 i586

libopenrm1-1.5.2-2mdv2007.0.i586.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html><head><title>OpenRM - RM Library (rmthread.c)</title></head>
<body bgcolor=white fgcolor=black>
<table width="100%" border=2 cellspacing=0 cellpadding=0 bgcolor="khaki" valign="center">
<th><img src="./images/ormsg.gif">
</th>
</table>
<spacer type=vertical size=15>
<h2>Index of OpenRM - RM Library</h2>
<spacer type=vertical size=15>
<a name="rmThreadCreate"> 
<pre><b>
 RMenum rmThreadCreate(RMthread *threadID,
	               void * (*threadFunc)(void *),
	               void *args)
</b></pre>
<pre>
 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 *.
</pre>
<menu><P>
 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().
</P>
<P>
 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.
</P>
<P>
 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.
</P>
<P>
 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.
</P></menu>
<i>librm library source file: rmthread.c </i><hr width="75%">
<a name="rmThreadJoin"> 
<pre><b>
 RMenum rmThreadJoin(RMthread *threadID,
	             void **threadReturn)
</b></pre>
<pre>
 RMthread *threadID - a handle to an RMthread object (input).
 void **threadReturn - a handle to a void * (modified).
</pre>
<menu><P>
 "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).
</P>
<P>
 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.
</P></menu>
<i>librm library source file: rmthread.c </i><hr width="75%">
<a name="rmMutexNew"> 
<pre><b>
 RMmutex * rmMutexNew(RMenum initLockState)
</b></pre>
<pre>
 RMenum initLockState - an RMenum value (input) specifying the
 initial state of the RMmutex returned to the caller.
</pre>
<menu><P>
 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.
</P>
<P>
 Valid values for initLockState are RM_MUTEX_LOCK or RM_MUTEX_UNLOCK.
</P>
<P>
 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).
</P>
<P>
 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.
</P>
<P>
 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.
</P>
<P>
 OpenRM mutex objects are intended to behave similarly in both
 Unix and Win32 environments.
</P></menu>
<i>librm library source file: rmthread.c </i><hr width="75%">
<a name="rmMutexDelete"> 
<pre><b>
 RMenum rmMutexDelete(RMmutex *toDelete)
</b></pre>
<pre>
 RMmutex * toDelete - a handle to an RMmutex object (modified).
</pre>
<menu><P>
 Releases resources associated with an RMmutex object. Callers
 should take care to ensure the RMmutex object is unlocked
 prior to calling rmMutexDelete().
</P>
<P>
 Returns RM_CHILL upon success, or RM_WHACKED upon failure.
</P>
<P>
 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).
</P>
<P>
 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.
</P>
<P>
 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.
</P>
<P>
 OpenRM mutex objects are intended to behave similarly in both
 Unix and Win32 environments.
</P></menu>
<i>librm library source file: rmthread.c </i><hr width="75%">
<a name="rmMutexLock"> 
<pre><b>
 RMenum rmMutexLock(RMmutex *toLock)
</b></pre>
<pre>
 RMmutex * toLock - a handle to an RMmutex object (modified).
</pre>
<menu><P>
 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.
</P>
<P>
 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).
</P>
<P>
 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.
</P>
<P>
 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.
</P>
<P>
 OpenRM mutex objects are intended to behave similarly in both
 Unix and Win32 environments.
</P></menu>
<i>librm library source file: rmthread.c </i><hr width="75%">
<a name="rmMutexUnlock"> 
<pre><b>
 RMenum rmMutexUnlock(RMmutex *toUnlock)
</b></pre>
<pre>
 RMmutex * toUnlock - a handle to an RMmutex object (modified).
</pre>
<menu><P>
 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.
</P>
<P>
 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).
</P>
<P>
 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.
</P>
<P>
 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.
</P>
<P>
 OpenRM mutex objects are intended to behave similarly in both
 Unix and Win32 environments.
</P></menu>
<i>librm library source file: rmthread.c </i><hr width="75%">
<a name="rmMutexTryLock"> 
<pre><b>
 RMenum rmMutexTryLock(RMmutex *toLock)
</b></pre>
<pre>
 RMmutex * toLock - a handle to an RMmutex object (modified).
</pre>
<menu><P>
 Attempts to lock an RMmutex object - this call is non-blocking.
</P>
<P>
 If the RMmutex object is locked, a value of RM_MUTEX_BUSY is
 returned to the caller, and the input RMmutex object remains
 unmodified.
</P>
<P>
 If the RMmutex was unlocked, this routine will lock it, and
 return RM_MUTEX_LOCK to the caller.
</P>
<P>
 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).
</P>
<P>
 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.
</P>
<P>
 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.
</P>
<P>
 OpenRM mutex objects are intended to behave similarly in both
 Unix and Win32 environments.
</P></menu>
<i>librm library source file: rmthread.c </i><hr width="75%">
</body></html>