SbThreadRWMutex Class Reference

Portable readers/writer lock class. More...

#include <Inventor/threads/SbThreadRWMutex.h>

Public Member Functions
	SbThreadRWMutex ()
	Create a read/write mutex.
	~SbThreadRWMutex ()
	Destructor.
int	writelock ()
	Request a write lock (exclusive access) for this mutex.
int	writeunlock ()
	Release a write lock.
int	readlock ()
	Request a read lock (non-exclusive access) for this mutex.
int	readunlock ()
	Release a read lock.
Deprecated
SoDEPRECATED	SbThreadRWMutex (const SbBool force)

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

Definition at line 93 of file SbThreadRWMutex.h.

Constructor & Destructor Documentation

SbThreadRWMutex() [1/2]

SbThreadRWMutex::SbThreadRWMutex

(

)

Create a read/write mutex.

SbThreadRWMutex() [2/2]

SoDEPRECATED SbThreadRWMutex::SbThreadRWMutex

(

const SbBool

force

)

~SbThreadRWMutex()

SbThreadRWMutex::~SbThreadRWMutex

(

)

Destructor.

Member Function Documentation

readlock()

int SbThreadRWMutex::readlock

(

)

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

Returns zero if successful.

readunlock()

int SbThreadRWMutex::readunlock

(

)

Release a read lock.

Returns zero if successful.

writelock()

int SbThreadRWMutex::writelock

(

)

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

Returns zero if successful.

writeunlock()

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