// balst_stacktraceconfigurationutil.h -*-C++-*- #ifndef INCLUDED_BALST_STACKTRACECONFIGURATIONUTIL #define INCLUDED_BALST_STACKTRACECONFIGURATIONUTIL #include <bsls_ident.h> BSLS_IDENT("$Id: $") //@PURPOSE: Provide utility for global configuration of stack trace. // //@CLASSES: // balst::StackTraceConfigurationUtil: global configuration of stack trace // //@DESCRIPTION: This component provides global configuration for stack traces // provided by the 'balst' package. // // Resolution of symbols, line numbers, and source file names is generally very // expensive and involves a lot of disk access. On Windows, such resolution // can also be very problematic for other reasons. // // Note that line number and source file name information is not available on // all platforms. If resolution is enabled, the stack trace will give as much // information as 'balst' has implemented for the platform. All platforms // support symbol names. // ///Configuration Options ///------------------------ // Currently this component provides one configuration option: // //: o [disable|enable]Resolution: Configures whether operations in 'balst' //: resolve symbols, line numbers, and source file names. By default, //: resolution is enabled. Resolution of symbols, line numbers, and source //: file names is generally expensive and involves disk access. On Windows //: platforms there are also thread-safety concerns with 'dbghlp.dll'. This //: option allows an application owner to globally prevent any resolution of //: symbols, line numbers, or source file names (by 'balst) in an //: application. // ///Usage ///----- // This section illustrates intended use of this component. // ///Example 1: Evaluating Boolean Value // - - - - - - - - - - - - - - - - - - // If neither 'enableResolution' nor 'disableResolution' have been called, the // default value of 'isResolutionDisabled' is 'false'. //.. // assert(false == // balst::StackTraceConfigurationUtil::isResolutionDisabled()); //.. // After that, the value tracks whether 'disableResolution' or // 'enableResolution' has been called. //.. // balst::StackTraceConfigurationUtil::disableResolution(); // // assert(true == balst::StackTraceConfigurationUtil::isResolutionDisabled()); // // balst::StackTraceConfigurationUtil::enableResolution(); // // assert(false == // balst::StackTraceConfigurationUtil::isResolutionDisabled()); //.. #include <balscm_version.h> namespace BloombergLP { namespace balst { // ================================= // class StackTraceConfigurationUtil // ================================= struct StackTraceConfigurationUtil { // This 'struct' provides a namespace for functions that configure the // behavior of stack traces performed by 'balst'. // CLASS METHODS static void disableResolution(); // Disable symbol, source file name, and line number resolution in // stack traces performed by 'balst'. Note that such resolution is // expensive, involving disk access, and on Windows platforms has // thread-safety concerns if the application is using 'dbghelp.dll'. // Disabling resolution allows an application owner to globally prevent // any resolution of symbols (by 'balst') in the process. static void enableResolution(); // Enable symbol resolution and source file name & line number // resolution on platforms that support them in stack traces performed // by 'balst'. Note that such resolution is expensive, involving disk // access, and on Windows platforms has thread-safety concerns if the // application is using 'dbghelp.dll'. Enabling resolution (the // default state) results in 'balst' stack traces giving as much // information as is available on the platform. static bool isResolutionDisabled(); // Return whether symbol and line number resolution in stack traces is // disabled. Note that if neither 'disableResolution' nor // 'enableResolution' have ever been called, this defaults to 'false'. }; } // close package namespace } // close enterprise namespace #endif // ---------------------------------------------------------------------------- // Copyright 2021 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 ----------------------------------