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

Subject: [Boost-commit] svn:boost r70873 - in sandbox/guild/pool: boost/pool libs/pool/doc
From: john_at_[hidden]
Date: 2011-04-02 13:51:31

Author: johnmaddock
Date: 2011-04-02 13:51:30 EDT (Sat, 02 Apr 2011)
New Revision: 70873
URL: http://svn.boost.org/trac/boost/changeset/70873

Log:
Update singleton_pool docs.
Binary files modified: 
   sandbox/guild/pool/libs/pool/doc/pool.pdf
Text files modified: 
   sandbox/guild/pool/boost/pool/singleton_pool.hpp |   122 +++++++++++++++++++++------------------ 
   1 files changed, 67 insertions(+), 55 deletions(-)

Modified: sandbox/guild/pool/boost/pool/singleton_pool.hpp
==============================================================================
--- sandbox/guild/pool/boost/pool/singleton_pool.hpp	(original)
+++ sandbox/guild/pool/boost/pool/singleton_pool.hpp	2011-04-02 13:51:30 EDT (Sat, 02 Apr 2011)
@@ -11,27 +11,12 @@
 
 /*!
   \file
-  \brief Singleton_pool class allows other pool interfaces
-  for types of the same size to share the same pool.
+  \brief The <tt>singleton_pool</tt> class allows other pool interfaces
+  for types of the same size to share the same underlying pool.
 
-  \details singleton_pool.hpp provides a template class singleton_pool,
-  which provides access to a pool as a singleton object.\n
-  For information on other pool-based interfaces, see the other pool interfaces.\n
-
-  Notes\n
-  The underlying pool p referenced by the static functions
-  in singleton_pool is actually declared in a way that it is:\n
-
-  1 Thread-safe if there is only one thread running before main() begins and after main() ends
-  -- all of the static functions of singleton_pool synchronize their access to p.
-
-  2 Guaranteed to be constructed before it is used --
-  thus, the simple static object in the synopsis above would actually be an incorrect implementation.
-  The actual implementation to guarantee this is considerably more complicated.
-
-  3 Note too that a different underlying pool p exists
-  for each different set of template parameters,
-  including implementation-specific ones.
+  \details Header singleton_pool.hpp provides a template class <tt>singleton_pool</tt>,
+  which provides access to a pool as a singleton object.
+  
 */
 
 #include <boost/pool/poolfwd.hpp>
@@ -45,15 +30,50 @@
 
 namespace boost {
 
- /*! singleton pool class allows other pool interfaces
-  for types of the same size to share the same pool.
-  \tparam Tag to allow different unbounded sets of singleton pools to exist.
-  \tparam RequestedSize  Size of pool requested.
-  \tparam UserAllocator User allocator, default = default_user_allocator_new_delete
-  \tparam Mutex The typedef mutex  publish the values of the template parameter Mutex (default details::pool::default_mutex).
-  \tparam NextSize The typedef static const value next_size publish the values of the template parameter NextSize, (default 32).
-  \tparam MaxSize  Maximum size.
- */
+ /*! 
+ The singleton_pool class allows other pool interfaces
+ for types of the same size to share the same pool.  Template
+ parameters are as follows:
+
+ <b>Tag</b> User-specified type to uniquely identify this pool: allows different unbounded sets of singleton pools to exist.
+
+ <b>RequestedSize</b> The size of each chunk returned by member function <tt>malloc()</tt>.
+
+ <B>UserAllocator</b> User allocator, default = default_user_allocator_new_delete.
+
+ <b>Mutex</B> This class is the type of mutex to use to protect simultaneous access to the underlying Pool. 
+ It is exposed so that users may declare some singleton pools normally (i.e., with synchronization), but 
+ some singleton pools without synchronization (by specifying <tt>details::pool::null_mutex</tt>) for efficiency reasons.
+ The member typedef <tt>mutex</tt> exposes the value of this template parameter.  The default for this
+ parameter is details::pool::default_mutex.
+
+ <B>NextSize</b> The value of this parameter is passed to the underlying Pool when it is created and
+ specifies the number of chunks to allocate in the first allocation request (defaults to 32).
+ The member typedef <tt>static const value next_size</tt> exposes the value of this template parameter.
+
+ <b>MaxSize</B>The value of this parameter is passed to the underlying Pool when it is created and
+ specifies the maximum number of chunks to allocate in any single allocation request (defaults to 0).
+
+  <b>Notes:</b>
+
+  The underlying pool <i>p</i> referenced by the static functions
+  in singleton_pool is actually declared in a way that is:
+
+  1 Thread-safe if there is only one thread running before main() begins and after main() ends
+  -- all of the static functions of singleton_pool synchronize their access to p.
+
+  2 Guaranteed to be constructed before it is used --
+  thus, the simple static object in the synopsis above would actually be an incorrect implementation.
+  The actual implementation to guarantee this is considerably more complicated.
+
+  3 Note too that a different underlying pool p exists
+  for each different set of template parameters,
+  including implementation-specific ones.
+
+  4 The underlying pool is constructed "as if" by:
+
+  pool<UserAllocator> p(RequestedSize, NextSize, MaxSize);
+  */
 
  template <typename Tag,
     unsigned RequestedSize,
@@ -61,31 +81,28 @@
     typename Mutex,
     unsigned NextSize,
     unsigned MaxSize >
-struct singleton_pool
+class singleton_pool
 {
   public:
-    typedef Tag tag; /*!< The Tag template parameter allows
+    typedef Tag tag; /*!< The Tag template parameter uniquely
+                     identifies this pool and allows
       different unbounded sets of singleton pools to exist.
       For example, the pool allocators use two tag classes to ensure that the
       two different allocator types never share the same underlying singleton pool.
       Tag is never actually used by singleton_pool.
     */
-    typedef Mutex mutex; //!< Mutex is guard (default details::pool::default_mutex).
-    typedef UserAllocator user_allocator; //!< User allocator, default = default_user_allocator_new_delete.
+    typedef Mutex mutex; //!< The type of mutex used to synchonise access to this pool (default <tt>details::pool::default_mutex</tt>).
+    typedef UserAllocator user_allocator; //!< The user-allocator used by this pool, default = <tt>default_user_allocator_new_delete</tt>.
     typedef typename pool<UserAllocator>::size_type size_type; //!< size_type of user allocator.
     typedef typename pool<UserAllocator>::difference_type difference_type; //!< difference_type of user allocator.
 
-    BOOST_STATIC_CONSTANT(unsigned, requested_size = RequestedSize);
-    BOOST_STATIC_CONSTANT(unsigned, next_size = NextSize);
+    BOOST_STATIC_CONSTANT(unsigned, requested_size = RequestedSize); //!< The size of each chunk allocated by this pool.
+    BOOST_STATIC_CONSTANT(unsigned, next_size = NextSize); //!< The number of chunks to allocate on the first allocation.
+
+private:
+    singleton_pool();
 
-  private:
-    /*! Mutex class is the type of mutex to use to protect
-       simultaneous access to the underlying Pool.
-       It is exposed so that users may declare some singleton pools normally
-       (i.e., with synchronization),
-       but some singleton pools without synchronization
-       (by specifying details::pool::null_mutex) for efficiency reasons.
-      */
+#ifndef BOOST_DOXYGEN
     struct pool_type: Mutex
     {
       pool<UserAllocator> p;
@@ -93,23 +110,18 @@
       :
       p(RequestedSize, NextSize)
       {
-      /*! Pool allocation
-       See the pair of functions size_type get_next_size() const; and void set_next_size(size_type);
-       that allow users to explicitly read and write the next_size value.
-       NextSize is the number of chunks to request from the system
-       the next time that object needs to allocate system memory.
-
-       \param RequestedSize value of this parameter is passed to the underlying Pool when it is created.
-       \param NextSize value of this parameter is passed to the underlying Pool when it is created.
-
-       \pre NextSize value should never be set to 0.
-      */
       }
     }; //  struct pool_type: Mutex
 
     typedef details::pool::singleton_default<pool_type> singleton;
+#else
+    //
+    // This is invoked when we build with Doxygen only:
+    //
+public:
+    static pool<UserAllocator> p; //!< For exposition only!
+#endif
 
-    singleton_pool();
 
   public:
     static void * malloc BOOST_PREVENT_MACRO_SUBSTITUTION()

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