Component bslma_deleterhelper [Package bslma]

Provide namespace for functions used to delete objects. More...

Namespaces
namespace	bslma

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage

Purpose:

Provide namespace for functions used to delete objects.

Classes:

bslma::DeleterHelper

non-primitive functions for deleting objects

See also:

Component bslma_rawdeleterguard, bslmf_ispolymporphic

Description:

This component provides non-primitive procedures used to delete objects of parameterized TYPE by first calling the destructor of the object, and then freeing the memory footprint of the object using a parameterized ALLOCATOR (allocator or pool) provided as a second argument. The "raw" method (deleteObjectRaw) should be used only if we are sure that the supplied object is not of a type that is a secondary base class -- i.e., the object's address is (numerically) the same as when it was originally dispensed by ALLOCATOR. The non-"raw" deleteObject has no such restriction. Note that this component will fail to compile when instantiated for a class that gives a false-positive for the type trait bsl::is_polymorphic. See the bslmf_ispolymporphic component for more details.

Usage:

The following my_RawDeleterGuard class defines a guard that unconditionally deletes a managed object upon destruction. Via the deleteObjectRaw method supplied by this component, the guard's destructor first destroys the managed object, then deallocates the footprint of the object. The declaration of my_RawDeleterGuard follows:

  template <class TYPE, class ALLOCATOR>
  class my_RawDeleterGuard {
      // This class implements a guard that unconditionally deletes a managed
      // object upon destruction by first invoking the object's destructor,
      // and then invoking the 'deallocate' method of an allocator (or pool)
      // of parameterized 'ALLOCATOR' type supplied at construction.

      // DATA
      TYPE      *d_object_p;     // managed object
      ALLOCATOR *d_allocator_p;  // allocator or pool (held, not owned)

      // NOT IMPLEMENTED
      my_RawDeleterGuard(const my_RawDeleterGuard&);
      my_RawDeleterGuard& operator=(const my_RawDeleterGuard&);

    public:
      // CREATORS
      my_RawDeleterGuard(TYPE *object, ALLOCATOR *allocator);
          // Create a raw deleter guard that unconditionally manages the
          // specified 'object', and that uses the specified 'allocator' to
          // delete 'object' upon the destruction of this guard.  The
          // behavior is undefined unless 'object' and 'allocator' are
          // non-zero, and 'allocator' supplied the memory for 'object'.
          // Note that 'allocator' must remain valid throughout the lifetime
          // of this guard.

      ~my_RawDeleterGuard();
          // Destroy this raw deleter guard and delete the object it manages
          // by first invoking the destructor of the (managed) object, and
          // then invoking the 'deallocate' method of the allocator (or pool)
          // that was supplied with the object at construction.
  };

The deleteObjectRaw method is used in the destructor as follows:

  template <class TYPE, class ALLOCATOR>
  inline
  my_RawDeleterGuard<TYPE, ALLOCATOR>::~my_RawDeleterGuard()
  {
      bslma::DeleterHelper::deleteObjectRaw(d_object_p, d_allocator_p);
  }

Note that we have denoted our guard to be a "raw" guard in keeping with this use of deleteObjectRaw (as opposed to deleteObject).