bslma_destructorguard.h

Go to the documentation of this file.

/// @file bslma_destructorguard.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bslma_destructorguard.h                                            -*-C++-*-
#ifndef INCLUDED_BSLMA_DESTRUCTORGUARD
#define INCLUDED_BSLMA_DESTRUCTORGUARD
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bslma_destructorguard bslma_destructorguard
/// @brief  Provide a guard to unconditionally manage an object.
/// @addtogroup bsl
/// @{
/// @addtogroup bslma
/// @{
/// @addtogroup bslma_destructorguard
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bslma_destructorguard-purpose"> Purpose</a>
/// * <a href="#bslma_destructorguard-classes"> Classes </a>
/// * <a href="#bslma_destructorguard-description"> Description </a>
///   * <a href="#bslma_destructorguard-usage"> Usage </a>
///
/// # Purpose {#bslma_destructorguard-purpose}
/// Provide a guard to unconditionally manage an object.
///
/// # Classes {#bslma_destructorguard-classes}
///
/// -  bslma::DestructorGuard: guard to unconditionally manage an object
///
/// @see  bslma_destructorproctor, bslma_autodestructor
///
/// # Description {#bslma_destructorguard-description}
/// This component provides a guard class template,
/// `bslma::DestructorGuard`, to unconditionally manage an (otherwise-unmanaged)
/// object of parameterized `TYPE` supplied at construction.  The managed object
/// is destroyed automatically when the guard object goes out of scope by
/// calling the (managed) object's destructor.
///
/// ## Usage {#bslma_destructorguard-usage}
///
///
/// Suppose we have a situation where one of the two constructors will be called
/// to create an object on the stack for performance reasons.  The construction
/// thus occurs within either of the branches of an `if` statement, so the
/// object itself, to survive the end of the "then" or "else" block, must be
/// constructed in a `bsls::ObjectBuffer`.  Once constructed, the object would
/// not be destroyed automatically, so to make sure it will be destroyed, we
/// place it under the management of a `bslma::DestructorGuard`.  After that, we
/// know that however the routine exits -- either by a return or as a result of
/// an exception being thrown -- the object will be destroyed.
/// @code
/// double usageExample(double startValue)
/// {
///     bsls::ObjectBuffer<std::vector<double> > buffer;
///     std::vector<double>& myVec = buffer.object();
///
///     if (startValue >= 0) {
///         new (&myVec) std::vector<double>(100, startValue);
///     }
///     else {
///         new (&myVec) std::vector<double>();
///     }
///
///     //***********************************************************
///     // Note the use of the destructor guard on 'myVec' (below). *
///     //***********************************************************
///
///     bslma::DestructorGuard<std::vector<double> > guard(&myVec);
/// @endcode
/// Note that regardless of how this routine terminates, `myVec` will be
/// destroyed.
/// @code
/// // ...
///
/// myVec.push_back(3.0);
/// @endcode
/// Note that `push_back` could allocate memory and therefore may throw.
/// However, if it does, `myVec` will be destroyed automatically along with
/// `guard`.
/// @code
/// if (myVec[0] >= 5.0) {
///     return 5.0;                                               // RETURN
/// @endcode
/// Note that `myVec` is automatically destroyed as the function returns.
/// @code
/// }
///
/// return myVec[myVec.size() / 2];
/// @endcode
/// Note that `myVec` is destroyed after the temporary containing the return
/// value is created.
/// @code
/// }
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bslma
 * @{
 */
/** @addtogroup bslma_destructorguard
 * @{
 */
 
#include <bslscm_version.h>
 
#include <bsls_assert.h>
 
 
 
namespace bslma {
 
                        // =====================
                        // class DestructorGuard
                        // =====================
 
/// This class implements a guard that unconditionally destroys a managed
/// object upon destruction by invoking the (managed) object's destructor.
///
/// See @ref bslma_destructorguard 
template <class TYPE>
class DestructorGuard {
 
    // DATA
    TYPE *d_object_p;  // managed object
 
  private:
    // NOT IMPLEMENTED
    DestructorGuard(const DestructorGuard<TYPE>&);
    DestructorGuard<TYPE>& operator=(const DestructorGuard<TYPE>&);
 
  public:
    // CREATORS
 
    /// Create a destructor guard that unconditionally manages the specified
    /// `object`, and invokes the destructor of `object` upon the destruction of this guard.  
    /// 
    /// \pre The behavior is undefined   unless
    /// `object` is non-zero.
    explicit DestructorGuard(TYPE *object);
 
    /// Destroy this destructor guard and the object it manages by invoking
    /// the destructor of the (managed) object.
    ~DestructorGuard();
};
 
// ============================================================================
//                          INLINE DEFINITIONS
// ============================================================================
 
                        // ---------------------
                        // class DestructorGuard
                        // ---------------------
 
// CREATORS
template <class TYPE>
inline
DestructorGuard<TYPE>::DestructorGuard(TYPE *object)
: d_object_p(object)
{
    BSLS_ASSERT_SAFE(object);
}
 
template <class TYPE>
inline
DestructorGuard<TYPE>::~DestructorGuard()
{
    BSLS_ASSERT_SAFE(d_object_p);
 
    d_object_p->~TYPE();
}
 
}  // close package namespace
 
#ifndef BDE_OPENSOURCE_PUBLICATION  // BACKWARD_COMPATIBILITY
// ============================================================================
//                           BACKWARD COMPATIBILITY
// ============================================================================
 
#ifdef bslma_DestructorGuard
#undef bslma_DestructorGuard
#endif
/// This alias is defined for backward compatibility.
#define bslma_DestructorGuard bslma::DestructorGuard
#endif  // BDE_OPENSOURCE_PUBLICATION -- BACKWARD_COMPATIBILITY
 
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2013 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */