Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r70857 - in sandbox/guild/pool: boost/pool libs/pool/doc
From: john_at_[hidden]
Date: 2011-04-02 12:09:54


Author: johnmaddock
Date: 2011-04-02 12:09:52 EDT (Sat, 02 Apr 2011)
New Revision: 70857
URL: http://svn.boost.org/trac/boost/changeset/70857

Log:
Fix missing object_pool constructors.
Fix bad comment in pool.hpp.
Update simple_segregated_storage docs.
Binary files modified:
   sandbox/guild/pool/libs/pool/doc/pool.pdf
Text files modified:
   sandbox/guild/pool/boost/pool/object_pool.hpp | 27 +++++++++
   sandbox/guild/pool/boost/pool/pool.hpp | 2
   sandbox/guild/pool/boost/pool/simple_segregated_storage.hpp | 107 +++++++++++++++++++++------------------
   sandbox/guild/pool/libs/pool/doc/jamfile.v2 | 2
   4 files changed, 86 insertions(+), 52 deletions(-)

Modified: sandbox/guild/pool/boost/pool/object_pool.hpp
==============================================================================
--- sandbox/guild/pool/boost/pool/object_pool.hpp (original)
+++ sandbox/guild/pool/boost/pool/object_pool.hpp 2011-04-02 12:09:52 EDT (Sat, 02 Apr 2011)
@@ -151,6 +151,31 @@
       return ret;
     }
 
+
+#if defined(BOOST_DOXYGEN)
+ template <class Arg1, ... class ArgN>
+ element_type * construct(Arg1&, ... ArgN&)
+ {
+ //! \returns A pointer to an object of type T, allocated in memory from the underlying pool
+ //! and constructed from arguments Arg1 to ArgN. The returned objected can be freed by a call to \ref destroy.
+ //! Otherwise the returned object will be automatically destroyed when *this is destroyed.
+ //!
+ //! \note Since the number and type of arguments to this function is totally arbitrary, a simple system has been
+ //! set up to automatically generate template construct functions. This system is based on the macro preprocessor
+ //! m4, which is standard on UNIX systems and also available for Win32 systems.\n\n
+ //! detail/pool_construct.m4, when run with m4, will create the file detail/pool_construct.ipp, which only defines
+ //! the construct functions for the proper number of arguments. The number of arguments may be passed into the
+ //! file as an m4 macro, NumberOfArguments; if not provided, it will default to 3.\n\n
+ //! For each different number of arguments (1 to NumberOfArguments), a template function is generated. There
+ //! are the same number of template parameters as there are arguments, and each argument's type is a reference
+ //! to that (possibly cv-qualified) template argument. Each possible permutation of the cv-qualifications is also generated.\n\n
+ //! Because each permutation is generated for each possible number of arguments, the included file size grows
+ //! exponentially in terms of the number of constructor arguments, not linearly. For the sake of rational
+ //! compile times, only use as many arguments as you need.\n\n
+ //! detail/pool_construct.bat and detail/pool_construct.sh are also provided to call m4, defining NumberOfArguments
+ //! to be their command-line parameter. See these files for more details.
+ }
+#else
 // Include automatically-generated file for family of template construct() functions.
 // Copy .inc renamed .ipp to conform to Doxygen include filename expectations, PAB 12 Jan 11.
 // But still get Doxygen warning:
@@ -167,7 +192,7 @@
 #else
 # include <boost/pool/detail/pool_construct_simple.ipp>
 #endif
-
+#endif
     void destroy(element_type * const chunk)
     { //! Destroys an object allocated with \ref construct.
       //!

Modified: sandbox/guild/pool/boost/pool/pool.hpp
==============================================================================
--- sandbox/guild/pool/boost/pool/pool.hpp (original)
+++ sandbox/guild/pool/boost/pool/pool.hpp 2011-04-02 12:09:52 EDT (Sat, 02 Apr 2011)
@@ -645,7 +645,7 @@
 bool pool<UserAllocator>::purge_memory()
 { //! pool must be ordered.
   //! Frees every memory block.
- /!
+ //!
   //! This function invalidates any pointers previously returned
   //! by allocation functions of t.
   //! \returns true if at least one memory block was freed.

Modified: sandbox/guild/pool/boost/pool/simple_segregated_storage.hpp
==============================================================================
--- sandbox/guild/pool/boost/pool/simple_segregated_storage.hpp (original)
+++ sandbox/guild/pool/boost/pool/simple_segregated_storage.hpp 2011-04-02 12:09:52 EDT (Sat, 02 Apr 2011)
@@ -12,9 +12,9 @@
 /*!
   \file
   \brief Simple Segregated Storage.
- \details 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,
+ \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.
@@ -33,11 +33,24 @@
 
 namespace boost {
 
-/*!
- 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.
+/*!
+
+\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
@@ -49,9 +62,6 @@
     simple_segregated_storage(const simple_segregated_storage &);
     void operator=(const simple_segregated_storage &);
 
- //! Try to malloc size n of partition_size at start location.
- //! \pre (n > 0), (start != 0), (nextof(start) != 0)
- //! \post (start != 0)
     static void * try_malloc_n(void * & start, size_type n,
         size_type partition_size);
 
@@ -61,18 +71,6 @@
       or is equal to 0 if the free list is empty.
     */
 
- //! \fn find_prev 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 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.
     void * find_prev(void * ptr);
 
     // for the sake of code readability :)
@@ -95,15 +93,6 @@
       //! \post empty()
     }
 
- //! 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 **.
     static void * segregate(void * block,
         size_type nsz, size_type npartition_sz,
         void * end = 0);
@@ -186,18 +175,15 @@
     }
 
    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)
- { //! Free N chunks.
- //! \pre chunks was previously allocated from *this with the same
- //! values for n and partition_size.
-
+ {
       if(n != 0)
         add_block(chunks, n * partition_size, partition_size);
     }
@@ -218,15 +204,22 @@
     }
 };
 
+//! 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)
-{ /*!
-\returns location previous to where ptr would go if it was in the free list.
-\note 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.
-*/
+{
   // Handle border case.
   if (first == 0 || std::greater<void *>()(first, ptr))
     return 0;
@@ -242,6 +235,15 @@
   }
 }
 
+//! 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,
@@ -249,10 +251,10 @@
     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.
+ // 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;
 
@@ -275,7 +277,9 @@
   return block;
 }
 
-//! The following function attempts to find n contiguous chunks
+//! \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}]
@@ -306,6 +310,11 @@
   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)

Modified: sandbox/guild/pool/libs/pool/doc/jamfile.v2
==============================================================================
--- sandbox/guild/pool/libs/pool/doc/jamfile.v2 (original)
+++ sandbox/guild/pool/libs/pool/doc/jamfile.v2 2011-04-02 12:09:52 EDT (Sat, 02 Apr 2011)
@@ -74,7 +74,7 @@
                         <doxygen:param>EXTRACT_PRIVATE=NO
          <doxygen:param>MACRO_EXPANSION=YES
                         <doxygen:param>EXPAND_ONLY_PREDEF=YES
- <doxygen:param>PREDEFINED="\"BOOST_PREVENT_MACRO_SUBSTITUTION=\" \"BOOST_STATIC_CONSTANT(t,v)=static const t v\""
+ <doxygen:param>PREDEFINED="\"BOOST_PREVENT_MACRO_SUBSTITUTION=\" \"BOOST_STATIC_CONSTANT(t,v)=static const t v\" \"BOOST_DOXYGEN=1\""
                         <xsl:param>"boost.doxygen.reftitle=Boost.Pool C++ Reference"
    ;
 

Modified: sandbox/guild/pool/libs/pool/doc/pool.pdf
==============================================================================
Binary files. No diff available.


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk