pcl::AutoReentrancyGuard Class Reference

Automatic reentrancy guard sentinel. More...

#include <Atomic.h>

Public Member Functions
	AutoReentrancyGuard (AtomicInt &guard)
	~AutoReentrancyGuard ()
	operator bool () const volatile

Detailed Description

AutoReentrancyGuard allows you to protect a block of code ensuring that it cannot be reentrant. All you need is a static AtomicInt variable that works as a 'busy state' flag persistent across function invocations.

Consider the following example:

 void foo()
{
   static AtomicInt flag;
   AutoReentrancyGuard guard( flag );
   if ( guard )
   {
      // protected code
   }
}

The function foo is not reentrant, so we want to protect it against possible reentrant invocations while the function's code is being executed.

The flag variable is initially zero (because AtomicInt's default constructor initializes its integer member to zero). The first time foo is called, AutoReentrancyGuard's constructor can change the value of flag from zero to one as an atomic operation. When this happens, AutoReentrancyGuard::operator bool() returns true, and the code protected within the if block can be executed.

When the guard object gets out of scope (just before the foo function returns), its class destructor resets flag to zero automatically, which permits the next non-reentrant execution of foo. However, if foo is called again before guard is destroyed, a newly constructed AutoReentrancyGuard object cannot make a transition 0 -> 1 with the static flag variable, and hence a reentrant execution of the protected code is not allowed (in this case, the function simply does nothing and returns after the if block). Note that the protected code can freely return from the function or throw exceptions; the flag variable will be reset to zero automatically when guard gets out of scope.

Since AutoReentrancyGuard uses AtomicInt to implement atomic transitions, code blocks can be protected against reentrant execution in multithreaded environments.

The macros PCL_REENTRANCY_GUARDED_BEGIN and PCL_REENTRANCY_GUARDED_END greatly simplify reentrancy protection. For example, the above code could be implemented as follows:

 void foo()
{
   PCL_REENTRANCY_GUARDED_BEGIN
   // protected code
   PCL_REENTRANCY_GUARDED_END
} 

In addition, the macros PCL_CLASS_REENTRANCY_GUARD and PCL_CLASS_REENTRANCY_GUARDED_BEGIN are useful for protection of all non-reentrant member functions of a class, and the macros PCL_MEMBER_REENTRANCY_GUARD and PCL_MEMBER_REENTRANCY_GUARDED_BEGIN provide protection of specific member functions. See these macros for examples.

Definition at line 443 of file Atomic.h.

Constructor & Destructor Documentation

AutoReentrancyGuard()

pcl::AutoReentrancyGuard::AutoReentrancyGuard ( AtomicInt &  guard )

inline

Constructs an AutoReentrancyGuard object to monitor the specified guard variable. If guard is zero, its value is set to one as an atomic operation. If guard is nonzero, its value is not changed.

Warning

The monitored guard variable must be either a static variable local to the function being protected, or a data member of the same class to which a protected member function belongs. Otherwise the protection mechanism will not work. This can be dangerous, especially because you may erroneously think that your code is being protected when it is not. In addition, the guard variable must be zero initially, or the protected code will never be allowed to work. We strongly recommend you don't use this class directly, but the PCL_REENTRANCY_GUARDED_BEGIN and PCL_REENTRANCY_GUARDED_END macros to implement function level protection, or PCL_CLASS_REENTRANCY_GUARD, PCL_CLASS_REENTRANCY_GUARDED_BEGIN and PCL_CLASS_REENTRANCY_GUARDED_END to implement per-instance function member protection.

Definition at line 465 of file Atomic.h.

References pcl::AtomicInt::TestAndSet().

~AutoReentrancyGuard()

pcl::AutoReentrancyGuard::~AutoReentrancyGuard ( )

inline

Destroys this object. If the value of the monitored guard variable (see the class constructor) was zero when this object was constructed, its value is reset to zero as an atomic operation.

Definition at line 476 of file Atomic.h.

References pcl::AtomicInt::Store().

Member Function Documentation

operator bool()

pcl::AutoReentrancyGuard::operator bool ( ) const volatile

inline

Returns true iff the value of the monitored guard variable (see the class constructor) was zero when this object was constructed.

Definition at line 486 of file Atomic.h.

---

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

• Atomic.h