// Copyright (C) 2000, 2001 Stephen Cleary
|
//
|
// Distributed under the Boost Software License, Version 1.0. (See
|
// accompanying file LICENSE_1_0.txt or copy at
|
// http://www.boost.org/LICENSE_1_0.txt)
|
//
|
// See http://www.boost.org for updates, documentation, and revision history.
|
|
#ifndef BOOST_SIMPLE_SEGREGATED_STORAGE_HPP
|
#define BOOST_SIMPLE_SEGREGATED_STORAGE_HPP
|
|
/*!
|
\file
|
\brief Simple Segregated Storage.
|
\details A simple segregated storage implementation:
|
simple segregated storage is the basic idea behind the Boost Pool library.
|
Simple segregated storage is the simplest, and probably the fastest,
|
memory allocation/deallocation algorithm.
|
It begins by partitioning a memory block into fixed-size chunks.
|
Where the block comes from is not important until implementation time.
|
A Pool is some object that uses Simple Segregated Storage in this fashion.
|
*/
|
|
// std::greater
|
#include <functional>
|
|
#include <boost/pool/poolfwd.hpp>
|
|
#ifdef BOOST_MSVC
|
#pragma warning(push)
|
#pragma warning(disable:4127) // Conditional expression is constant
|
#endif
|
|
#ifdef BOOST_POOL_VALIDATE
|
# define BOOST_POOL_VALIDATE_INTERNALS validate();
|
#else
|
# define BOOST_POOL_VALIDATE_INTERNALS
|
#endif
|
|
namespace boost {
|
|
/*!
|
|
\brief Simple Segregated Storage is the simplest, and probably the fastest,
|
memory allocation/deallocation algorithm. It is responsible for
|
partitioning a memory block into fixed-size chunks: where the block comes from
|
is determined by the client of the class.
|
|
\details Template class simple_segregated_storage controls access to a free list of memory chunks.
|
Please note that this is a very simple class, with preconditions on almost all its functions. It is intended to
|
be the fastest and smallest possible quick memory allocator - e.g., something to use in embedded systems.
|
This class delegates many difficult preconditions to the user (i.e., alignment issues).
|
|
An object of type simple_segregated_storage<SizeType> is empty if its free list is empty.
|
If it is not empty, then it is ordered if its free list is ordered. A free list is ordered if repeated calls
|
to <tt>malloc()</tt> will result in a constantly-increasing sequence of values, as determined by <tt>std::less<void *></tt>.
|
A member function is <i>order-preserving</i> if the free list maintains its order orientation (that is, an
|
ordered free list is still ordered after the member function call).
|
|
*/
|
template <typename SizeType>
|
class simple_segregated_storage
|
{
|
public:
|
typedef SizeType size_type;
|
|
private:
|
simple_segregated_storage(const simple_segregated_storage &);
|
void operator=(const simple_segregated_storage &);
|
|
static void * try_malloc_n(void * & start, size_type n,
|
size_type partition_size);
|
|
protected:
|
void * first; /*!< This data member is the free list.
|
It points to the first chunk in the free list,
|
or is equal to 0 if the free list is empty.
|
*/
|
|
void * find_prev(void * ptr);
|
|
// for the sake of code readability :)
|
static void * & nextof(void * const ptr)
|
{ //! The return value is just *ptr cast to the appropriate type. ptr must not be 0. (For the sake of code readability :)
|
//! As an example, let us assume that we want to truncate the free list after the first chunk.
|
//! That is, we want to set *first to 0; this will result in a free list with only one entry.
|
//! The normal way to do this is to first cast first to a pointer to a pointer to void,
|
//! and then dereference and assign (*static_cast<void **>(first) = 0;).
|
//! This can be done more easily through the use of this convenience function (nextof(first) = 0;).
|
//! \returns dereferenced pointer.
|
return *(static_cast<void **>(ptr));
|
}
|
|
public:
|
// Post: empty()
|
simple_segregated_storage()
|
:first(0)
|
{ //! Construct empty storage area.
|
//! \post empty()
|
}
|
|
static void * segregate(void * block,
|
size_type nsz, size_type npartition_sz,
|
void * end = 0);
|
|
// Same preconditions as 'segregate'
|
// Post: !empty()
|
void add_block(void * const block,
|
const size_type nsz, const size_type npartition_sz)
|
{ //! Add block
|
//! Segregate this block and merge its free list into the
|
//! free list referred to by "first".
|
//! \pre Same as segregate.
|
//! \post !empty()
|
BOOST_POOL_VALIDATE_INTERNALS
|
first = segregate(block, nsz, npartition_sz, first);
|
BOOST_POOL_VALIDATE_INTERNALS
|
}
|
|
// Same preconditions as 'segregate'
|
// Post: !empty()
|
void add_ordered_block(void * const block,
|
const size_type nsz, const size_type npartition_sz)
|
{ //! add block (ordered into list)
|
//! This (slower) version of add_block segregates the
|
//! block and merges its free list into our free list
|
//! in the proper order.
|
BOOST_POOL_VALIDATE_INTERNALS
|
// Find where "block" would go in the free list
|
void * const loc = find_prev(block);
|
|
// Place either at beginning or in middle/end
|
if (loc == 0)
|
add_block(block, nsz, npartition_sz);
|
else
|
nextof(loc) = segregate(block, nsz, npartition_sz, nextof(loc));
|
BOOST_POOL_VALIDATE_INTERNALS
|
}
|
|
// default destructor.
|
|
bool empty() const
|
{ //! \returns true only if simple_segregated_storage is empty.
|
return (first == 0);
|
}
|
|
void * malloc BOOST_PREVENT_MACRO_SUBSTITUTION()
|
{ //! Create a chunk.
|
//! \pre !empty()
|
//! Increment the "first" pointer to point to the next chunk.
|
BOOST_POOL_VALIDATE_INTERNALS
|
void * const ret = first;
|
|
// Increment the "first" pointer to point to the next chunk.
|
first = nextof(first);
|
BOOST_POOL_VALIDATE_INTERNALS
|
return ret;
|
}
|
|
void free BOOST_PREVENT_MACRO_SUBSTITUTION(void * const chunk)
|
{ //! Free a chunk.
|
//! \pre chunk was previously returned from a malloc() referring to the same free list.
|
//! \post !empty()
|
BOOST_POOL_VALIDATE_INTERNALS
|
nextof(chunk) = first;
|
first = chunk;
|
BOOST_POOL_VALIDATE_INTERNALS
|
}
|
|
void ordered_free(void * const chunk)
|
{ //! This (slower) implementation of 'free' places the memory
|
//! back in the list in its proper order.
|
//! \pre chunk was previously returned from a malloc() referring to the same free list
|
//! \post !empty().
|
|
// Find where "chunk" goes in the free list
|
BOOST_POOL_VALIDATE_INTERNALS
|
void * const loc = find_prev(chunk);
|
|
// Place either at beginning or in middle/end.
|
if (loc == 0)
|
(free)(chunk);
|
else
|
{
|
nextof(chunk) = nextof(loc);
|
nextof(loc) = chunk;
|
}
|
BOOST_POOL_VALIDATE_INTERNALS
|
}
|
|
void * malloc_n(size_type n, size_type partition_size);
|
|
//! \pre chunks was previously allocated from *this with the same
|
//! values for n and partition_size.
|
//! \post !empty()
|
//! \note If you're allocating/deallocating n a lot, you should
|
//! be using an ordered pool.
|
void free_n(void * const chunks, const size_type n,
|
const size_type partition_size)
|
{
|
BOOST_POOL_VALIDATE_INTERNALS
|
if(n != 0)
|
add_block(chunks, n * partition_size, partition_size);
|
BOOST_POOL_VALIDATE_INTERNALS
|
}
|
|
// pre: chunks was previously allocated from *this with the same
|
// values for n and partition_size.
|
// post: !empty()
|
void ordered_free_n(void * const chunks, const size_type n,
|
const size_type partition_size)
|
{ //! Free n chunks from order list.
|
//! \pre chunks was previously allocated from *this with the same
|
//! values for n and partition_size.
|
|
//! \pre n should not be zero (n == 0 has no effect).
|
BOOST_POOL_VALIDATE_INTERNALS
|
if(n != 0)
|
add_ordered_block(chunks, n * partition_size, partition_size);
|
BOOST_POOL_VALIDATE_INTERNALS
|
}
|
#ifdef BOOST_POOL_VALIDATE
|
void validate()
|
{
|
int index = 0;
|
void* old = 0;
|
void* ptr = first;
|
while(ptr)
|
{
|
void* pt = nextof(ptr); // trigger possible segfault *before* we update variables
|
++index;
|
old = ptr;
|
ptr = nextof(ptr);
|
}
|
}
|
#endif
|
};
|
|
//! Traverses the free list referred to by "first",
|
//! and returns the iterator previous to where
|
//! "ptr" would go if it was in the free list.
|
//! Returns 0 if "ptr" would go at the beginning
|
//! of the free list (i.e., before "first").
|
|
//! \note Note that this function finds the location previous to where ptr would go
|
//! if it was in the free list.
|
//! It does not find the entry in the free list before ptr
|
//! (unless ptr is already in the free list).
|
//! Specifically, find_prev(0) will return 0,
|
//! not the last entry in the free list.
|
//! \returns location previous to where ptr would go if it was in the free list.
|
template <typename SizeType>
|
void * simple_segregated_storage<SizeType>::find_prev(void * const ptr)
|
{
|
// Handle border case.
|
if (first == 0 || std::greater<void *>()(first, ptr))
|
return 0;
|
|
void * iter = first;
|
while (true)
|
{
|
// if we're about to hit the end, or if we've found where "ptr" goes.
|
if (nextof(iter) == 0 || std::greater<void *>()(nextof(iter), ptr))
|
return iter;
|
|
iter = nextof(iter);
|
}
|
}
|
|
//! Segregate block into chunks.
|
//! \pre npartition_sz >= sizeof(void *)
|
//! \pre npartition_sz = sizeof(void *) * i, for some integer i
|
//! \pre nsz >= npartition_sz
|
//! \pre Block is properly aligned for an array of object of
|
//! size npartition_sz and array of void *.
|
//! The requirements above guarantee that any pointer to a chunk
|
//! (which is a pointer to an element in an array of npartition_sz)
|
//! may be cast to void **.
|
template <typename SizeType>
|
void * simple_segregated_storage<SizeType>::segregate(
|
void * const block,
|
const size_type sz,
|
const size_type partition_sz,
|
void * const end)
|
{
|
// Get pointer to last valid chunk, preventing overflow on size calculations
|
// The division followed by the multiplication just makes sure that
|
// old == block + partition_sz * i, for some integer i, even if the
|
// block size (sz) is not a multiple of the partition size.
|
char * old = static_cast<char *>(block)
|
+ ((sz - partition_sz) / partition_sz) * partition_sz;
|
|
// Set it to point to the end
|
nextof(old) = end;
|
|
// Handle border case where sz == partition_sz (i.e., we're handling an array
|
// of 1 element)
|
if (old == block)
|
return block;
|
|
// Iterate backwards, building a singly-linked list of pointers
|
for (char * iter = old - partition_sz; iter != block;
|
old = iter, iter -= partition_sz)
|
nextof(iter) = old;
|
|
// Point the first pointer, too
|
nextof(block) = old;
|
|
return block;
|
}
|
|
//! \pre (n > 0), (start != 0), (nextof(start) != 0)
|
//! \post (start != 0)
|
//! The function attempts to find n contiguous chunks
|
//! of size partition_size in the free list, starting at start.
|
//! If it succeds, it returns the last chunk in that contiguous
|
//! sequence, so that the sequence is known by [start, {retval}]
|
//! If it fails, it does do either because it's at the end of the
|
//! free list or hits a non-contiguous chunk. In either case,
|
//! it will return 0, and set start to the last considered
|
//! chunk. You are at the end of the free list if
|
//! nextof(start) == 0. Otherwise, start points to the last
|
//! chunk in the contiguous sequence, and nextof(start) points
|
//! to the first chunk in the next contiguous sequence (assuming
|
//! an ordered free list).
|
template <typename SizeType>
|
void * simple_segregated_storage<SizeType>::try_malloc_n(
|
void * & start, size_type n, const size_type partition_size)
|
{
|
void * iter = nextof(start);
|
while (--n != 0)
|
{
|
void * next = nextof(iter);
|
if (next != static_cast<char *>(iter) + partition_size)
|
{
|
// next == 0 (end-of-list) or non-contiguous chunk found
|
start = iter;
|
return 0;
|
}
|
iter = next;
|
}
|
return iter;
|
}
|
|
//! Attempts to find a contiguous sequence of n partition_sz-sized chunks. If found, removes them
|
//! all from the free list and returns a pointer to the first. If not found, returns 0. It is strongly
|
//! recommended (but not required) that the free list be ordered, as this algorithm will fail to find
|
//! a contiguous sequence unless it is contiguous in the free list as well. Order-preserving.
|
//! O(N) with respect to the size of the free list.
|
template <typename SizeType>
|
void * simple_segregated_storage<SizeType>::malloc_n(const size_type n,
|
const size_type partition_size)
|
{
|
BOOST_POOL_VALIDATE_INTERNALS
|
if(n == 0)
|
return 0;
|
void * start = &first;
|
void * iter;
|
do
|
{
|
if (nextof(start) == 0)
|
return 0;
|
iter = try_malloc_n(start, n, partition_size);
|
} while (iter == 0);
|
void * const ret = nextof(start);
|
nextof(start) = nextof(iter);
|
BOOST_POOL_VALIDATE_INTERNALS
|
return ret;
|
}
|
|
} // namespace boost
|
|
#ifdef BOOST_MSVC
|
#pragma warning(pop)
|
#endif
|
|
#endif
|
