SbThreadRWMutex Class Reference
[Threads]

Portable readers/writer lock class. More...

#include <Inventor/threads/SbThreadRWMutex.h>

List of all members.

Public Member Functions
	SbThreadRWMutex (const SbBool force=FALSE)
	~SbThreadRWMutex ()
int	writelock ()
int	writeunlock ()
int	readlock ()
int	readunlock ()

---

Detailed Description

Portable readers/writer lock class.

This class provides read/write blocking. It is implemented using the pthreads API on UNIX/Linux and the Win32 API on Microsoft Windows.

A readers/writer lock works like this:
Any number of threads can hold a read lock on this object at the same time. While any thread holds a read lock on this object, all requests for a write lock will block. Conversely, only one thread can hold a write lock on this object at any time. While a thread holds a write lock on this object, all requests for a read lock by other threads will block. As a convenience, the thread holding the write lock may obtain any number of read locks, as long as all read locks are released before the write lock is released.

A readers/writer lock is appropriate for a resource that is frequently "read" (its value accessed) and is not often modified. Particularly if the "read" access must be held for a significant amount of time. (If all accesses, both read and write, are quite short then it may be more efficient to use the SbThreadMutex class.) For example, the SoDB::readlock and SoDB::writelock methods use an SbThreadRWMutex to control access to the scene graph. All Open Inventor actions automatically call SoDB::readlock to gain read access before beginning a traversal. This allows, for example, multiple render threads to safely traverse ("read") the scene graph in parallel.

Generally, acquiring a read or write lock on an SbThreadRWMutex is more expensive (takes more time) than acquiring a lock on an SbThreadMutex. As with any synchronization object, failure to release a lock will usually result in a "deadlock" situation that prevents the application from running. SbThreadAutoReadLock and SbThreadAutoWriteLock provide a "safe" way to acquire a lock that will be automatically released when the object goes out of scope.

It is not necessary to use this class in order to use multiple threads with Open Inventor. It is provided only as a convenience. (However, note that you should use pthreads on UNIX/Linux and Win32 on Windows to be certain of compatibility with Open Inventor.)

SEE ALSO

SbThread, SbThreadAutoLock, SbThreadAutoReadLock, SbThreadAutoWriteLock, SbThreadBarrier, SbThreadMutex

---

Constructor & Destructor Documentation

SbThreadRWMutex::SbThreadRWMutex

(

const SbBool

force = FALSE

)

Create a read/write mutex.

SbThreadRWMutex::~SbThreadRWMutex

(

)

Destructor.

---

Member Function Documentation

int SbThreadRWMutex::readlock

(

)

Request a read lock (non-exclusive access) for this mutex.

Returns zero if successful.

int SbThreadRWMutex::readunlock

(

)

Release a read lock.

Returns zero if successful.

int SbThreadRWMutex::writelock

(

)

Request a write lock (exclusive access) for this mutex.

Returns zero if successful.

int SbThreadRWMutex::writeunlock

(

)

Release a write lock.

Returns zero if successful.

---

The documentation for this class was generated from the following file:

• Inventor/threads/SbThreadRWMutex.h