bslstl_exception.h

Go to the documentation of this file.

/// @file bslstl_exception.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bslstl_exception.h                                                 -*-C++-*-
#ifndef INCLUDED_BSLSTL_EXCEPTION
#define INCLUDED_BSLSTL_EXCEPTION
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bslstl_exception bslstl_exception
/// @brief  Provide an implementation of `uncaught_exceptions`.
/// @addtogroup bsl
/// @{
/// @addtogroup bslstl
/// @{
/// @addtogroup bslstl_exception
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bslstl_exception-purpose"> Purpose</a>
/// * <a href="#bslstl_exception-classes"> Classes </a>
/// * <a href="#bslstl_exception-description"> Description </a>
///   * <a href="#bslstl_exception-usage"> Usage </a>
///     * <a href="#bslstl_exception-example-1-determining-if-the-stack-is-being-unwound"> Example 1: Determining if the stack is being unwound. </a>
///
/// # Purpose {#bslstl_exception-purpose}
/// Provide an implementation of @ref uncaught_exceptions .
///
/// # Classes {#bslstl_exception-classes}
///
///
/// **Canonical header:**  bsl_exception.h
///
/// # Description {#bslstl_exception-description}
/// This component defines a function `bsl::uncaught_exceptions`.
/// For C++17 and later, this is an alias for `std::uncaught_exceptions`. Before
/// C++17, we emulate the functionality.
///
/// ## Usage {#bslstl_exception-usage}
///
///
/// In this section we show intended use of this component.
///
/// ### Example 1: Determining if the stack is being unwound. {#bslstl_exception-example-1-determining-if-the-stack-is-being-unwound}
///
///
/// Suppose we have a class that does some processing in it's destructor, but
/// we don't want to do this if an exception is "in flight".  `bslmt::OnceGuard`
/// is an example of this kind of functionality.
///
/// First, we create a class with an `int d_exception_count` member variable,
/// and record the number of in-flight exceptions in the constructor.
/// @code
/// struct ExceptionAware {
///     ExceptionAware() : d_exception_count(bsl::uncaught_exceptions()) {}
///     ~ExceptionAware();
///     int d_exception_count;
///  };
/// @endcode
/// Then, we implement the destructor
/// @code
/// ExceptionAware::~ExceptionAware () {
///     if (bsl::uncaught_exceptions() > d_exception_count) {
///         // The stack is being unwound
///     }
///     else {
///         // The object is being destroyed normally
///     }
/// }
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bslstl
 * @{
 */
/** @addtogroup bslstl_exception
 * @{
 */
 
#include <bslscm_version.h>
 
#include <bsls_compilerfeatures.h>
#include <bsls_libraryfeatures.h>
 
#include <exception>
 
namespace bsl {
#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_BASELINE_LIBRARY
    using std::uncaught_exceptions;
#else
    /// Return the number of exceptions that have been thrown or rethrown in
    /// the current thread that have not been caught.  If the C++17 baseline
    /// library is not available, this function may return 1 even if more
    /// than 1 uncaught exception exists, but if guaranteed to return 0 if
    /// there are no uncaught exceptions.
    int uncaught_exceptions() throw();
#endif
}  // close namespace bsl
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2023 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */