[Boost-commit] svn:boost r70857 - in sandbox/guild/pool: boost/pool libs/pool/doc

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.