bslma_deallocateobjectproctor

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage

Purpose

Provide a proctor to conditionally unwind object allocation.

Classes

• bslma::DeallocateObjectProctor: proctor to conditionally unwind allocation.

See also

bslma_deallocatebytesproctor, bslma_deleteobjectproctor

Description

This component provides a proctor class template, bslma::DeallocateObjectProctor, that conditionally reverses the effect of bslma::AllocatorUtil::allocateObject<TYPE> or '(TYPE *) bslmAllocator->allocate(n)'. Upon destruction, this proctor deallocates the object from the specified allocator or pool without calling the object's destructor. The proctor's constructor takes the same arguments as bslma::AllocatorUtil::deallocateObject, making it straightforward to allocate an object using allocateObject and protect it using DeallocateObjectProctor.

As with all proctors, this class is used to automatically reclaim a resource in the event that a function ends prematurely, e.g., via an exception. After allocating an object, an exception-safe function would create a DeallocateObjectProctor to manage the new object's memory. If the operation completes successfully, the code calls the proctor's release method, which disengages the proctor. If, however, the function exits while the proctor is still engaged, the proctor's destructor will deallocate the managed memory.

The DeallocateObjectProctor template has two template parameters: the ALLOCATOR type used to reclaim storage and the object TYPE managed by the proctor. If ALLOCATOR is a non-pointer type and TYPE is omitted, it is deduced as ALLOCATOR::value_type. However, if TYPE is supplied, it overrides ALLOCATOR::value_type.

If ALLOCATOR is a non-pointer type, the proctor uses bslma::AllocatorUtil::deleteObject(a, ptr, n) to reclaim storage, where a is the allocator, ptr is the address of the managed object, and n is the number of managed objects. Otherwise, if ALLOCATOR is a pointer type, the proctor reclaims memory by calling a->deallocate(ptr). Instantiating DeallocateObjectProctor with a pointer-type ALLOCATOR is appropriate for classes derived from bslma::Allocator and for BDE-style pool types, i.e., classes for which a->deallocate(ptr) is well formed.

Usage

These examples illustrate the intended use of this component.

Example 1: Class having an owning pointer

---

In this example, we create a class, my_Manager, having an owning pointer to an object of another class, my_Data. Because it owns the my_Data object, my_Manager is responsible for allocating, constructing, deallocating, and destroying it.

First, we define the my_Data class, which holds an integer value and counts how many times its constructor and destructor have been called. Its constructor will throw an exception if its integer argument equals the number of constructor calls before construction:

 #include <bslma_allocatorutil.h>
 #include <bslma_bslallocator.h>
 #include <bslma_testallocator.h>
 
 class my_Data {
 
     // DATA
     int d_value;
 
     // CLASS DATA
     static int s_numConstructed;
     static int s_numDestroyed;
 
   public:
     // CLASS METHODS
     static int numConstructed() { return s_numConstructed; }
     static int numDestroyed()   { return s_numDestroyed;   }
 
     // CREATORS
     explicit my_Data(int v) : d_value(v)
     {
         if (v == s_numConstructed) throw s_numConstructed;
         ++s_numConstructed;
     }
     my_Data(const my_Data& original);
     ~my_Data() { ++s_numDestroyed; }
 };
 
 int my_Data::s_numConstructed = 0;
 int my_Data::s_numDestroyed   = 0;

Next, we define my_Manager as an allocator-aware class holding a pointer to my_Data and maintaining its own count of constructor invocations:

 class my_Manager {
 
     // DATA
     bsl::allocator<my_Data>  d_allocator;
     my_Data                 *d_data_p;
 
     // CLASS DATA
     static int s_numConstructed;
 
   public:
     // TYPES
     typedef bsl::allocator<> allocator_type;
 
     // CLASS METHODS
     static int numConstructed() { return s_numConstructed; }
 
     // CREATORS
     explicit my_Manager(int                   v,
                       const allocator_type& allocator = allocator_type());
     my_Manager(const my_Manager& original);
     ~my_Manager();
 
     // ...
 };
 
 int my_Manager::s_numConstructed = 0;

Next, we define the constructor for my_Manager, which begins by allocating a my_Data object:

 my_Manager::my_Manager(int v, const allocator_type& allocator)
     : d_allocator(allocator), d_data_p(0)
 {
     d_data_p = bslma::AllocatorUtil::allocateObject<my_Data>(allocator);

Then, the my_Manager constructor constructs the my_Data object in the allocated memory. However, as the constructor might throw it first protects the data object with a bslma::DeallocateObjectProctor:

     bslma::DeallocateObjectProctor<allocator_type, my_Data>
                                             proctor(d_allocator, d_data_p);
     bslma::ConstructionUtil::construct(d_data_p, d_allocator, v);

Then, once the construct operation completes successfully, we can release the data object from the proctor. Only then do we increment the construction count:

     proctor.release();
     ++s_numConstructed;
 }

Next, we define the my_Manager destructor, which destroys and deallocates its data object:

 my_Manager::~my_Manager()
 {
     d_data_p->~my_Data();
     bslma::AllocatorUtil::deallocateObject(d_allocator, d_data_p);
 }

Now, we use a bslma::TestAllocator to verify that, under normal (non exceptional) circumstances, constructing a my_Manager object will result in one block of memory being allocated and one invocation of the my_Data constructor:

 int main()
 {
     bslma::TestAllocator ta;
 
     {
         my_Manager obj1(7, &ta);
         assert(1 == ta.numBlocksInUse());
         assert(1 == ta.numBlocksTotal());
         assert(1 == my_Manager::numConstructed());
     }
     assert(0 == ta.numBlocksInUse());
     assert(1 == ta.numBlocksTotal());
     assert(1 == my_Manager::numConstructed());

Finally, when the my_Data constructor does throw, a block is allocated but we verify that the my_Manager constructor did not complete and that the block was deallocated, resulting in no leaks:

     try {
         my_Manager obj2(1, &ta);
         assert(false && "Can't get here");
     }
     catch (int e) {
         assert(1 == e);
         assert(0 == ta.numBlocksInUse());
         assert(2 == ta.numBlocksTotal());
         assert(1 == my_Manager::numConstructed());
     }
     assert(1 == my_Manager::numConstructed());
 }