scoped pointer paired with a mutex More...

#include <cassert>
#include <boost/noncopyable.hpp>
#include <boost/scoped_ptr.hpp>
#include <boost/thread/shared_mutex.hpp>
#include <boost/thread/locks.hpp>

Include dependency graph for guarded_ptr.hpp:

Go to the source code of this file.

Classes
class	moost::guarded_ptr< T >
	Wrapper around shared_ptr that guards the referenced object with a mutex. More...
class	moost::guarded_ptr< T >::shared_access
	Objects of this class represent a shared lock of the guarded_ptr's mutex. More...
class	moost::guarded_ptr< T >::exclusive_access
	Objects of this class represent an exclusive lock of the guarded_ptr's mutex. More...
class	moost::guarded_ptr< T >::upgradable_access
	Objects of this class represent an upgradable lock of the guarded_ptr's mutex. More...
class	moost::guarded_ptr< T >::upgradable_access::upgrade
	Objects of this class represent an upgrade of an upgradable lock. More...
Namespaces
namespace	moost
	Creates a unique temporary directory; removed on scope exit.

Detailed Description

scoped pointer paired with a mutex

This file is part of libmoost.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

If objects of type 'foo' are not inherently thread-safe to use, a guarded_ptr can be used to add locking around the foo object. A guarded_ptr cannot make any arbitrary object automagically thread-safe, but it pairs the pointer to the object with a mutex and only gives you access to the object while you are holding a lock. The developer still needs to know what locks (shared or exclusive) are necessary to carry out operations on the object. Shared locks will only grant you access to a const-reference of the object.

Also, just like with other smart pointers, you need to follow some rules in order to benefit from the smartness. There are certainly ways to obtain a pointer to the original object through some methods. Saving such a pointer and using it in other places will undermine the benefits. (As it would if you did the same for e.g. a shared_ptr.)

 moost::guarded_ptr<foo> bar(new foo);

The guarded_ptr object has no methods to call. Upon destruction it will take of destruction of the foo object.

To use the object referenced by bar, a lock must be acquired.

 moost::guarded_ptr<foo>::shared_access barlock(bar);
 barlock->some_const_method_of_foo();

The lock is kept until barlock runs out of scope. The shared_access object keeps are shared lock of the mutex in the guarded_ptr object. shared_access implements operator* and operator->, which both return a const-pointer to the underlying foo object. If you need to call non-const methods, you will have to acquire an exclusive lock, for which a class exclusive_lock exists.

 moost::guarded_ptr<foo>::exclusive_access barlock(bar);
 barlock->some_method_of_foo();

The exclusive_access class works much like shared_access, but it acquires a full, exclusive lock of the mutex within guarded_ptr. It allows to call const and non-const methods of the underlying object.

There is also an upgradable_access class.

 moost::guarded_ptr<foo>::upgradable_access barlock(bar);
 barlock->some_const_method_of_foo();
 moost::guarded_ptr<foo>::upgradable_access::upgrade barlock2(barlock);
 barlock2->some_method_of_foo();

The upgradable_access constructor acquires an upgradable lock. It secures shared access to the object which can later be upgraded to exclusive access. The upgradable_access object itself only yields const-pointers to the underlying object, but an upgrade object can be constructed from it, which then also offers non-const pointers. Upon construction of the (first) upgrade object from an upgradable_access object, the lock held by upgradable_access is promoted to an exclusive lock.

Note:: Objects of types shared_access, exclusive_access, upgradable_access and upgrade must never outlive the objects they were created from.

Definition in file guarded_ptr.hpp.

Classes

Namespaces

Detailed Description