bslmt_configuration.h

Go to the documentation of this file.

/// @file bslmt_configuration.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bslmt_configuration.h                                              -*-C++-*-
#ifndef INCLUDED_BSLMT_CONFIGURATION
#define INCLUDED_BSLMT_CONFIGURATION
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bslmt_configuration bslmt_configuration
/// @brief  Provide utilities to allow configuration of values for BCE.
/// @addtogroup bsl
/// @{
/// @addtogroup bslmt
/// @{
/// @addtogroup bslmt_configuration
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bslmt_configuration-purpose"> Purpose</a>
/// * <a href="#bslmt_configuration-classes"> Classes </a>
/// * <a href="#bslmt_configuration-description"> Description </a>
///   * <a href="#bslmt_configuration-usage"> Usage </a>
///     * <a href="#bslmt_configuration-example-1-demonstrate-accessing-&-modifying-the-default-thread-stack-size"> Example 1: Demonstrate Accessing & Modifying the Default Thread Stack Size </a>
///
/// # Purpose {#bslmt_configuration-purpose}
/// Provide utilities to allow configuration of values for BCE.
///
/// # Classes {#bslmt_configuration-classes}
///
/// -  bslmt::Configuration: namespace for utilities managing default BCE values
///
/// @see  bslmt_threadattributes, bslmt_threadutil
///
/// # Description {#bslmt_configuration-description}
/// This component defines a utility `struct`,
/// `bslmt::Configuration`, that is a name space for pure functions used for
/// providing access to, and configuring, default values for BCE-relevant
/// parameters.  The `bslmt::Configuration` utility currently provides static
/// methods to access and modify the BCE library's default stack size, as well
/// as functions that access the platform's native default stack size and guard
/// size.  The BDE default stack size is initially configured to
/// `bslmt::ThreadAttributes::BSLMT_UNSET_STACK_SIZE`, in which case thread
/// creation is to use the native default thread stack size.
///
/// ## Usage {#bslmt_configuration-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Demonstrate Accessing & Modifying the Default Thread Stack Size {#bslmt_configuration-example-1-demonstrate-accessing-&-modifying-the-default-thread-stack-size}
///
///
/// In this example we demonstrate how to access both the platform's native and
/// BDE configured default stack sizes, and then to set the default stack size
/// used by BDE.  Note that the value returned by `defaultThreadStackSize` may
/// be adjusted from that provided by the underlying operating system to reflect
/// the actual amount of stack memory available to a created thread.  Note that
/// operations creating a thread should perform a similar inverse adjustment
/// when configuring the new thread's stack size (see @ref bslmt_threadutil ).
///
/// First, we examine the platform's native thread stack size:
/// @code
/// const int nativeDefault =
///                       bslmt::Configuration::nativeDefaultThreadStackSize();
///
/// assert(nativeDefault > 0);
/// @endcode
/// Then, we verify that `defaultThreadStackSize` is unset.
/// @code
/// assert(bslmt::ThreadAttributes::e_UNSET_STACK_SIZE ==
///                            bslmt::Configuration::defaultThreadStackSize());
/// @endcode
/// Next, we define `newDefaultStackSize` to some size other than the platform's
/// native default stack size:
/// @code
/// const int newDefaultStackSize = nativeDefault * 2;
/// @endcode
/// Now, we set the default size for BCE to the new size:
/// @code
/// bslmt::Configuration::setDefaultThreadStackSize(newDefaultStackSize);
/// @endcode
/// Finally, we verify that BCE's default thread stack size has been set to the
/// value we specified:
/// @code
/// assert(bslmt::Configuration::defaultThreadStackSize() ==
///                                                       newDefaultStackSize);
/// assert(bslmt::Configuration::defaultThreadStackSize() != nativeDefault);
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bslmt
 * @{
 */
/** @addtogroup bslmt_configuration
 * @{
 */
 
#include <bslscm_version.h>
 
 
namespace bslmt {
 
                           // ====================
                           // struct Configuration
                           // ====================
 
/// This `struct` provides a namespace for a suite of functions that are
/// used to manage the configuration of default values used in `bslmt`.
/// Specifically, these functions manage the default value of thread stack
/// size and provide access to the platform's native guard size, but may be
/// extended to govern more traits in the future.
struct Configuration {
 
    // CLASS METHODS
 
    /// Return the value set by the last call to
    /// `setDefaultThreadStackSize`; if `setDefaultThreadStackSize` has
    /// never been called, return `ThreadAttributes::BSLMT_UNSET_STACK_SIZE`
    /// which will signal thread creation to use the thread stack size
    /// native to the platform.
    static int defaultThreadStackSize();
 
    /// Return the "native" default thread stack size (in bytes) as
    /// determined by the underlying platform.  Note that this value may be
    /// influenced by the choice of platform, environment variables,
    /// compiler/linker options, or shell configuration, and typically
    /// varies wildly among different platforms.
    static int nativeDefaultThreadStackSize();
 
    /// Return the default thread stack guard size (in bytes) determined by
    /// the underlying platform.  Note that this value reflects semantics,
    /// and may be influenced by the choice of platform, environment
    /// variables, compiler/linker options, or shell configuration, and may
    /// vary somewhat among different platforms.
    static int nativeDefaultThreadGuardSize();
 
    /// Return a "reasonable" value for the default thread stack size (in
    /// bytes), which, unlike `nativeDefaultThreadStackSize`, is constant
    /// across all platforms of a given word size.  This value is large
    /// enough to guarantee that an automatic array of at least 250 * 1024
    /// pointers may be declared in the top level routine of the thread.
    static int recommendedDefaultThreadStackSize();
 
    /// Set the default thread stack size to the specified `numBytes`.  If a
    /// minimum thread stack size is known for the underlying platform (i.e.
    /// `PTHREAD_STACK_MIN` is defined) and `numBytes` is below that
    /// minimum, the stack size will be that minimum.  The behavior is
    /// undefined unless `0 <= numBytes`.
    static void setDefaultThreadStackSize(int numBytes);
};
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2015 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */