📄 auto_buffer.hpp
字号:
/* /////////////////////////////////////////////////////////////////////////
* File: stlsoft/memory/auto_buffer.hpp (originally MTLocBfr.h, ::SynesisStl)
*
* Purpose: Contains the auto_buffer template class.
*
* Created: 19th January 2002
* Updated: 12th August 2007
*
* Home: http://stlsoft.org/
*
* Copyright (c) 2002-2007, Matthew Wilson and Synesis Software
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* - Redistributions of source code must retain the above copyright notice, this
* list of conditions and the following disclaimer.
* - Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
* - Neither the name(s) of Matthew Wilson and Synesis Software nor the names of
* any contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*
* ////////////////////////////////////////////////////////////////////// */
/** \file stlsoft/memory/auto_buffer.hpp
*
* \brief [C++ only] Definition of the stlsoft::auto_buffer class template
* (\ref group__library__memory "Memory" Library).
*/
#ifndef STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER
#define STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define STLSOFT_VER_STLSOFT_MEMORY_HPP_AUTO_BUFFER_MAJOR 5
# define STLSOFT_VER_STLSOFT_MEMORY_HPP_AUTO_BUFFER_MINOR 1
# define STLSOFT_VER_STLSOFT_MEMORY_HPP_AUTO_BUFFER_REVISION 1
# define STLSOFT_VER_STLSOFT_MEMORY_HPP_AUTO_BUFFER_EDIT 154
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
/* /////////////////////////////////////////////////////////////////////////
* Compatibility
*/
/*
[Incompatibilies-start]
STLSOFT_COMPILER_IS_GCC: __GNUC__ < 3
[Incompatibilies-end]
[DocumentationStatus:Ready]
*/
/* /////////////////////////////////////////////////////////////////////////
* Includes
*/
#ifndef STLSOFT_INCL_STLSOFT_H_STLSOFT
# include <stlsoft/stlsoft.h>
#endif /* !STLSOFT_INCL_STLSOFT_H_STLSOFT */
#ifndef STLSOFT_INCL_STLSOFT_MEMORY_HPP_ALLOCATOR_FEATURES
# include <stlsoft/memory/allocator_features.hpp> // for STLSOFT_LF_ALLOCATOR_ALLOCATE_HAS_HINT
#endif /* !STLSOFT_INCL_STLSOFT_MEMORY_HPP_ALLOCATOR_FEATURES */
#ifndef STLSOFT_INCL_STLSOFT_MEMORY_HPP_ALLOCATOR_SELECTOR
# include <stlsoft/memory/allocator_selector.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_MEMORY_HPP_ALLOCATOR_SELECTOR */
#ifndef STLSOFT_INCL_STLSOFT_ALGORITHMS_HPP_POD
# include <stlsoft/algorithms/pod.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_HPP_ALGORITHMS_POD */
#ifndef STLSOFT_INCL_STLSOFT_UTIL_HPP_STD_SWAP
# include <stlsoft/util/std_swap.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_UTIL_HPP_STD_SWAP */
#ifdef _STLSOFT_AUTO_BUFFER_ALLOW_UDT
# define _STLSOFT_AUTO_BUFFER_ALLOW_NON_POD
# ifdef STLSOFT_CF_PRAGMA_MESSAGE_SUPPORT
# pragma message("_STLSOFT_AUTO_BUFFER_ALLOW_UDT is deprecated. Use _STLSOFT_AUTO_BUFFER_ALLOW_NON_POD instead")
# endif /* STLSOFT_CF_PRAGMA_MESSAGE_SUPPORT */
#endif /* _STLSOFT_AUTO_BUFFER_ALLOW_UDT */
#if defined(STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT)
# ifndef STLSOFT_INCL_STLSOFT_UTIL_STD_HPP_ITERATOR_HELPER
# include <stlsoft/util/std/iterator_helper.hpp>
# endif /* !STLSOFT_INCL_STLSOFT_UTIL_STD_HPP_ITERATOR_HELPER */
#endif /* STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT */
#ifndef _STLSOFT_AUTO_BUFFER_ALLOW_NON_POD
# ifndef STLSOFT_INCL_STLSOFT_UTIL_HPP_CONSTRAINTS
# include <stlsoft/util/constraints.hpp>
# endif /* !STLSOFT_INCL_STLSOFT_UTIL_HPP_CONSTRAINTS */
#endif /* _STLSOFT_AUTO_BUFFER_ALLOW_NON_POD */
#ifndef STLSOFT_INCL_STLSOFT_COLLECTIONS_UTIL_HPP_COLLECTIONS
# include <stlsoft/collections/util/collections.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_COLLECTIONS_UTIL_HPP_COLLECTIONS */
#ifdef STLSOFT_UNITTEST
# include <algorithm>
# if defined(STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT)
# include <numeric>
# endif /* STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT */
# include <stdio.h>
#endif /* STLSOFT_UNITTEST */
/* /////////////////////////////////////////////////////////////////////////
* Namespace
*/
#ifndef _STLSOFT_NO_NAMESPACE
namespace stlsoft
{
#endif /* _STLSOFT_NO_NAMESPACE */
/* /////////////////////////////////////////////////////////////////////////
* Classes
*/
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# if !defined(STLSOFT_COMPILER_IS_BORLAND) && \
!defined(STLSOFT_COMPILER_IS_DMC)
struct auto_buffer_internal_default
{
enum { min_value = 32 };
enum { max_value = 256 };
enum { division_factor = 2 };
};
template <ss_typename_param_k T>
struct auto_buffer_internal_size_calculator
: private auto_buffer_internal_default
{
private:
// Stupid, stupid, stupid GCC requires them all to share the same
// enum, which totally sucks. It whinges about comparisons between
// enumerals (sic.) of different types. Thankfully it's irrelevant
// because they're private
enum
{
min_value = auto_buffer_internal_default::min_value
, max_value = auto_buffer_internal_default::max_value
, division_factor = auto_buffer_internal_default::division_factor
, divided_value_ = static_cast<int>((division_factor * max_value) / sizeof(T))
, divided_value = (max_value < divided_value_)
? max_value
: divided_value_
};
public:
enum { value = 1 == sizeof(T)
? max_value
: divided_value < min_value
? min_value
: divided_value };
};
STLSOFT_TEMPLATE_SPECIALISATION
struct auto_buffer_internal_size_calculator<ss_char_a_t>
{
enum { value = auto_buffer_internal_default::max_value };
};
# if defined(STLSOFT_CF_NATIVE_WCHAR_T_SUPPORT) || \
defined(STLSOFT_CF_TYPEDEF_WCHAR_T_SUPPORT)
STLSOFT_TEMPLATE_SPECIALISATION
struct auto_buffer_internal_size_calculator<ss_char_w_t>
{
enum { value = auto_buffer_internal_default::max_value };
};
# endif /* STLSOFT_CF_NATIVE_WCHAR_T_SUPPORT */
# endif /* compiler */
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
// class auto_buffer
//
/** \brief This class provides an efficient variable automatic buffer
*
* \ingroup group__library__memory
*
* \param T The type of the elements in the array
* \param SPACE The number of elements in the array. For translators that
* support default template arguments, this is defaulted to <b>256</b>
* \param A The allocator type. Defaults to
* \link stlsoft::allocator_selector allocator_selector<T>::allocator_type\endlink
* for translators that support default template arguments.
*
* This class provides an efficient replacement for dynamic memory block
* allocation when the block size generally falls under a predictable limit. In
* such cases, significant performance benefits can be achieved by using an
* instance of a parameterisation of auto_buffer, whose size parameter SPACE
* is set to a level to cater for most of the requested sizes. Only where
* the size of the buffer needs to be larger than this limit does an
* allocation occur from the heap/free-store via the given allocator.
*
* Using <code>auto_buffer</code> means one can avoid use of heap memory in
* circumstances where stack memory is unsuitable, i.e. where there is no
* maximum size to a memory requirement, or the maximum size is potentially
* very large (and considerably larger than the median size). Consider the
* following code extract from the core of the
* <a href = "http://pantheios.org/">Pantheios</a> logging library:
\code
int pantheios_log_n( pan_sev_t severity
, size_t numSlices
, pan_slice_t const* slices)
{
typedef stlsoft::auto_buffer<char, 2048> buffer_t;
// Calculate the total size of the log statement, by summation of the slice array
const size_t n = std::accumulate(stlsoft::member_selector(slices, &pan_slice_t::len)
, stlsoft::member_selector(slices + numSlices, &pan_slice_t::len)
, size_t(0));
buffer_t buffer(1 + n);
. . .
\endcode
*
* This use of auto_buffer illustrates two important features:
* - there is no (compile-time) limit on the maximum size of a log statement
* - memory is only allocated from the heap in the case where the total statement length >= 2047 bytes.
*
* Without auto_buffer, we would have three choices, all bad:
*
* 1. We could go to the heap in all cases:
\code
int pantheios_log_n( pan_sev_t severity
, size_t numSlices
, pan_slice_t const* slices)
{
typedef stlsoft::vector<char> buffer_t;
// Calculate the total size of the log statement, by summation of the slice array
const size_t n = std::accumulate(stlsoft::member_selector(slices, &pan_slice_t::len)
, stlsoft::member_selector(slices + numSlices, &pan_slice_t::len)
, size_t(0));
buffer_t buffer(1 + n);
. . .
\endcode
* But this would have an unacceptable performance hit (since the vast
* majority of log statements are less than 2K in extent).
*
* 2. We could use a stack buffer, and truncate any log statement exceeding
* the limit:
\code
int pantheios_log_n( pan_sev_t severity
, size_t numSlices
, pan_slice_t const* slices)
{
// Calculate the total size of the log statement, by summation of the slice array
const size_t n = std::accumulate(stlsoft::member_selector(slices, &pan_slice_t::len)
, stlsoft::member_selector(slices + numSlices, &pan_slice_t::len)
, size_t(0));
char buffer[2048];
. . . // make sure to truncate the statement to a max 2047 characters
\endcode
* But this would unnecessarily constrain users of the Pantheios logging
* functionality.
*
* 3. Finally, we could synthesise the functionality of auto_buffer
* manually, as in:
\code
int pantheios_log_n( pan_sev_t severity
, size_t numSlices
, pan_slice_t const* slices)
{
// Calculate the total size of the log statement, by summation of the slice array
const size_t n = std::accumulate(stlsoft::member_selector(slices, &pan_slice_t::len)
, stlsoft::member_selector(slices + numSlices, &pan_slice_t::len)
, size_t(0));
char buff[2048];
char *buffer = (n < 2048) ? &buff[0] : new char[1 + n];
. . .
if(buffer != &buff[0])
{
delete [] buffer;
}
\endcode
* But this is onerous manual fiddling, and exception-unsafe. What would be
* the point, when auto_buffer already does this (safely) for us?
*
* As a consequence of its blending of the best features of stack and heap
* memory, auto_buffer is an invaluable component in the implementation of
* many components within the STLSoft libraries, and in several other
* open-source projects, including:
* <a href = "http://synesis.com.au/software/b64.html">b64</a>,
* <a href = "http://openrj.org/">Open-RJ</a>,
* <a href = "http://pantheios.org/">Pantheios</a>,
* <a href = "http://recls.org/">recls</a>,
* and
* <a href = "http://shwild.org/">shwild</a>.
*
* \remarks auto_buffer works correctly whether the given allocator throws an
* exception on allocation failure, or returns <code>NULL</code>. In the
* latter case, construction failure to allocate is reflected by the size()
* method returning 0.
*
* \remarks The design of auto_buffer is described in Chapter 32 of
* <a href = "http://imperfectcplusplus.com">Imperfect C++</a>, and its
* interface is discussed in detail in Section 16.2 of
* <a href = "http://extendedstl.com">Extended STL, volume 1</a>.
*
* \note With version 1.9 of STLSoft, the order of the space and allocator
* arguments were reversed. Further, the allocator default changed from
* stlsoft::new_allocator to <code>std::allocator</code> for translators that support
* the standard library. If you need the old characteristics, you can
* <code>\#define</code> the symbol <b>STLSOFT_AUTO_BUFFER_USE_PRE_1_9_CHARACTERISTICS</b>.
*/
#if defined(STLSOFT_COMPILER_IS_MSVC) && \
_MSC_VER < 1200
# define STLSOFT_AUTO_BUFFER_USE_PRE_1_9_CHARACTERISTICS
#endif /* compiler */
#if defined(STLSOFT_AUTO_BUFFER_USE_PRE_1_9_CHARACTERISTICS)
# ifdef STLSOFT_AUTO_BUFFER_NEW_FORM
# undef STLSOFT_AUTO_BUFFER_NEW_FORM
# endif /* STLSOFT_AUTO_BUFFER_NEW_FORM */
// //////////////////////////////////////////////
// This is the pre-1.9 template parameter list
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -