|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r68238 - sandbox/guild/pool/boost/pool/detail
From: pbristow_at_[hidden]
Date: 2011-01-18 13:15:09
Author: pbristow
Date: 2011-01-18 13:15:06 EST (Tue, 18 Jan 2011)
New Revision: 68238
URL: http://svn.boost.org/trac/boost/changeset/68238
Log:
Added more Doxygen comments
Text files modified:
sandbox/guild/pool/boost/pool/detail/ct_gcd_lcm.hpp | 84 +++++++++++++++++++-----------
sandbox/guild/pool/boost/pool/detail/gcd_lcm.hpp | 20 +++++--
sandbox/guild/pool/boost/pool/detail/guard.hpp | 45 +++++++++++++--
sandbox/guild/pool/boost/pool/detail/singleton.hpp | 110 ++++++++++++++++++++++++---------------
4 files changed, 171 insertions(+), 88 deletions(-)
Modified: sandbox/guild/pool/boost/pool/detail/ct_gcd_lcm.hpp
==============================================================================
--- sandbox/guild/pool/boost/pool/detail/ct_gcd_lcm.hpp (original)
+++ sandbox/guild/pool/boost/pool/detail/ct_gcd_lcm.hpp 2011-01-18 13:15:06 EST (Tue, 18 Jan 2011)
@@ -8,6 +8,25 @@
#ifndef BOOST_POOL_CT_GCD_LCM_HPP
#define BOOST_POOL_CT_GCD_LCM_HPP
+/*!
+ \file
+ \brief Compile-Time GCD and LCM.
+ \details Provides two compile-time algorithms: greatest common divisor and least common multiple.
+
+ Selected Quotation from the C++ Standard
+
+ 5.19/1: Expressions: Constant Expressions:
+ ". . . An integral constant expression can involve only literals (2.13),
+ enumerators, const variables or static data members of integral or
+ enumeration types initialized with constant expressions (8.5),
+ non-type template parameters of integral or enumeration types,
+ and sizeof expressions.
+ Floating literals (2.13.3) can appear only if they are cast to integral or enumeration types.
+ Only type conversions to integral or enumeration types can be used.
+ In particular, except in sizeof expressions, functions, class objects, pointers, or references
+ shall not be used, and assignment, increment, decrement, function-call,
+ or comma operators shall not be used."
+*/
#include <boost/static_assert.hpp>
#include <boost/type_traits/ice.hpp>
@@ -19,49 +38,54 @@
// Compile-time calculation of greatest common divisor and least common multiple
-//
// ct_gcd is a compile-time algorithm that calculates the greatest common
// divisor of two unsigned integers, using Euclid's algorithm.
//
// assumes: A != 0 && B != 0
-//
#ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
-namespace details {
-template <unsigned A, unsigned B, bool Bis0>
-struct ct_gcd_helper;
-template <unsigned A, unsigned B>
-struct ct_gcd_helper<A, B, false>
+namespace details
{
- BOOST_STATIC_CONSTANT(unsigned, A_mod_B_ = A % B);
- BOOST_STATIC_CONSTANT(unsigned, value =
- (::boost::details::pool::details::ct_gcd_helper<
- B, static_cast<unsigned>(A_mod_B_),
- ::boost::type_traits::ice_eq<A_mod_B_, 0>::value
- >::value) );
-};
-template <unsigned A, unsigned B>
-struct ct_gcd_helper<A, B, true>
-{
- BOOST_STATIC_CONSTANT(unsigned, value = A);
-};
+ template <unsigned A, unsigned B, bool Bis0>
+ struct ct_gcd_helper;
+ template <unsigned A, unsigned B>
+ struct ct_gcd_helper<A, B, false>
+ { //! Helper function.
+ //! \tparam A compile-time unsigned integer constant.
+ //! \tparam B compile-time unsigned integer constant.
+ //! \tparam Bis0 parameter B == 0, or not.
+
+ BOOST_STATIC_CONSTANT(unsigned, A_mod_B_ = A % B);
+ BOOST_STATIC_CONSTANT(unsigned, value =
+ (::boost::details::pool::details::ct_gcd_helper<
+ B, static_cast<unsigned>(A_mod_B_),
+ ::boost::type_traits::ice_eq<A_mod_B_, 0>::value
+ >::value) );
+ };
+ template <unsigned A, unsigned B>
+ struct ct_gcd_helper<A, B, true>
+ {
+ BOOST_STATIC_CONSTANT(unsigned, value = A);
+ };
} // namespace details
template <unsigned A, unsigned B>
struct ct_gcd
-{
+{ //! The greatest common divisor of A and B.
+ //! \pre A != 0 && B != 0
BOOST_STATIC_ASSERT(A != 0 && B != 0);
BOOST_STATIC_CONSTANT(unsigned, value =
(::boost::details::pool::details::ct_gcd_helper<A, B, false>::value) );
};
#else
-
+// BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION == true
// Thanks to Peter Dimov for providing this workaround!
+
namespace details {
template<unsigned A> struct ct_gcd2
-{
+{ //! workaround for NO_TEMPLATE_PARTIAL_SPECIALIZATION (Thanks to Peter Dimov).
template<unsigned B>
struct helper
{
@@ -76,22 +100,20 @@
} // namespace details
template<unsigned A, unsigned B> struct ct_gcd
-{
+{ //! Compile-time algorithm that calculates the greatest common divisor of A and B.
+ //! \pre A != 0 && B != 0.
BOOST_STATIC_ASSERT(A != 0 && B != 0);
enum { value = details::ct_gcd2<A>::helper<B>::value };
};
-#endif
+#endif // BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
-//
-// ct_lcm is a compile-time algorithm that calculates the least common
-// multiple of two unsigned integers.
-//
-// assumes: A != 0 && B != 0
-//
template <unsigned A, unsigned B>
struct ct_lcm
-{
+{ //! Compile-time algorithm that calculates the least common multiple
+ //! of two unsigned integers.
+
+ //! \pre A != 0 && B != 0.
BOOST_STATIC_CONSTANT(unsigned, value =
(A / ::boost::details::pool::ct_gcd<A, B>::value * B) );
};
Modified: sandbox/guild/pool/boost/pool/detail/gcd_lcm.hpp
==============================================================================
--- sandbox/guild/pool/boost/pool/detail/gcd_lcm.hpp (original)
+++ sandbox/guild/pool/boost/pool/detail/gcd_lcm.hpp 2011-01-18 13:15:06 EST (Tue, 18 Jan 2011)
@@ -9,14 +9,18 @@
#ifndef BOOST_POOL_GCD_LCM_HPP
#define BOOST_POOL_GCD_LCM_HPP
+/*!
+ \file
+ \brief GCD and LCM two generic integer algorithms: greatest common divisor and least common multiple..
+*/
+
namespace boost {
namespace details {
namespace pool {
-// Greatest common divisor and least common multiple
+// Greatest common divisor and least common multiple.
-//
// gcd is an algorithm that calculates the greatest common divisor of two
// integers, using Euclid's algorithm.
//
@@ -24,7 +28,10 @@
// Recommended: A > B
template <typename Integer>
Integer gcd(Integer A, Integer B)
-{
+{ //! algorithm that calculates the greatest common divisor of two
+ //! integers, using Euclid's algorithm.
+ //! For faster results, ensure A > B.
+ //! \pre A != 0 && B != 0.
do
{
const Integer tmp(B);
@@ -36,14 +43,15 @@
}
//
-// lcm is an algorithm that calculates the least common multiple of two
-// integers.
+// lcm is an algorithm that calculates the least common multiple of two integers.
//
// Pre: A > 0 && B > 0
// Recommended: A > B
template <typename Integer>
Integer lcm(const Integer & A, const Integer & B)
-{
+{ //! Algorithm that calculates the least common multiple of two integers.
+ //! For faster results, ensure A > B.
+ //! \pre A != 0 && B != 0.
Integer ret = A;
ret /= gcd(A, B);
ret *= B;
Modified: sandbox/guild/pool/boost/pool/detail/guard.hpp
==============================================================================
--- sandbox/guild/pool/boost/pool/detail/guard.hpp (original)
+++ sandbox/guild/pool/boost/pool/detail/guard.hpp 2011-01-18 13:15:06 EST (Tue, 18 Jan 2011)
@@ -9,28 +9,57 @@
#ifndef BOOST_POOL_GUARD_HPP
#define BOOST_POOL_GUARD_HPP
-// Extremely Light-Weight guard glass
+/*!
+ \file
+ \brief Extremely Light-Weight guard class.
+ \details Auto-lock/unlock-er
+ detail/guard.hpp provides a type guard<Mutex>
+ that allows scoped access to the Mutex's locking and unlocking operations.
+ It is used to ensure that a Mutex is unlocked, even if an exception is thrown.
+*/
namespace boost {
namespace details {
namespace pool {
-template <typename Mutex>
+template <typename Mutex> //!< \tparam Mutex (platform-specific) mutex class.
class guard
-{
+{ //! Locks the mutex, binding guard<Mutex> to Mutex.
+ /*! Example:
+ Given a (platform-specific) mutex class, we can wrap code as follows:
+
+ extern mutex global_lock;
+
+ static void f()
+ {
+ boost::details::pool::guard<mutex> g(global_lock);
+ // g's constructor locks "global_lock"
+
+ ... // do anything:
+ // throw exceptions
+ // return
+ // or just fall through
+ } // g's destructor unlocks "global_lock"
+ */
private:
Mutex & mtx;
- guard(const guard &);
+ guard(const guard &); //!< Guards the mutex, ensuring unlocked on destruction, even if exception is thrown.
void operator=(const guard &);
public:
explicit guard(Mutex & nmtx)
- :mtx(nmtx) { mtx.lock(); }
-
- ~guard() { mtx.unlock(); }
-};
+ :mtx(nmtx)
+ { //! Locks the mutex of the guard class.
+ mtx.lock();
+ }
+
+ ~guard()
+ { //! destructor unlocks the mutex of the guard class.
+ mtx.unlock();
+ }
+}; // class guard
} // namespace pool
} // namespace details
Modified: sandbox/guild/pool/boost/pool/detail/singleton.hpp
==============================================================================
--- sandbox/guild/pool/boost/pool/detail/singleton.hpp (original)
+++ sandbox/guild/pool/boost/pool/detail/singleton.hpp 2011-01-18 13:15:06 EST (Tue, 18 Jan 2011)
@@ -9,62 +9,86 @@
#ifndef BOOST_POOL_SINGLETON_HPP
#define BOOST_POOL_SINGLETON_HPP
-// The following code might be put into some Boost.Config header in a later revision
+/*!
+\file
+\brief Access to a Singleton of a class type.
+detail/singleton.hpp provides a way to access a Singleton of a class type.
+This is not a general Singleton solution!
+It is restricted in that the class type must have a default constructor.
+\details
+ Guarantees\n
+ The singleton instance is guaranteed to be constructed before main() begins,
+ and destructed after main() ends.
+ Furthermore, it is guaranteed to be constructed before
+ the first call to singleton_default<T>::instance() is complete
+ (even if called before main() begins).
+ Thus, if there are not multiple threads running except within main(),
+ and if all access to the singleton is restricted by mutexes,
+ then this guarantee allows a thread-safe singleton.
+
+ The following helper classes are placeholders for a generic "singleton"
+ class. The classes below support usage of singletons, including use in
+ program startup/shutdown code, AS LONG AS there is only one thread
+ running before main() begins, and only one thread running after main()
+ exits.
+
+ This class is also limited in that it can only provide singleton usage for
+ classes with default constructors.
+
+
+ The design of this class is somewhat twisted, but can be followed by the
+ calling inheritance. Let us assume that there is some user code that
+ calls "singleton_default<T>::instance()". The following (convoluted)
+ sequence ensures that the same function will be called before main():
+ instance() contains a call to create_object.do_nothing()
+ Thus, object_creator is implicitly instantiated, and create_object
+ must exist.
+ Since create_object is a static member, its constructor must be
+ called before main().
+ The constructor contains a call to instance(), thus ensuring that
+ instance() will be called before main().
+ The first time instance() is called (i.e., before main()) is the
+ latest point in program execution where the object of type T
+ can be created.
+ Thus, any call to instance() will auto-magically result in a call to
+ instance() before main(), unless already present.
+ Furthermore, since the instance() function contains the object, instead
+ of the singleton_default class containing a static instance of the
+ object, that object is guaranteed to be constructed (at the latest) in
+ the first call to instance(). This permits calls to instance() from
+ static code, even if that code is called before the file-scope objects
+ in this file have been initialized.
+*/
+
+// The following code might be put into some Boost.Config header in a later revision.
#ifdef __BORLANDC__
# pragma option push -w-inl
#endif
-//
-// The following helper classes are placeholders for a generic "singleton"
-// class. The classes below support usage of singletons, including use in
-// program startup/shutdown code, AS LONG AS there is only one thread
-// running before main() begins, and only one thread running after main()
-// exits.
-//
-// This class is also limited in that it can only provide singleton usage for
-// classes with default constructors.
-//
-
-// The design of this class is somewhat twisted, but can be followed by the
-// calling inheritance. Let us assume that there is some user code that
-// calls "singleton_default<T>::instance()". The following (convoluted)
-// sequence ensures that the same function will be called before main():
-// instance() contains a call to create_object.do_nothing()
-// Thus, object_creator is implicitly instantiated, and create_object
-// must exist.
-// Since create_object is a static member, its constructor must be
-// called before main().
-// The constructor contains a call to instance(), thus ensuring that
-// instance() will be called before main().
-// The first time instance() is called (i.e., before main()) is the
-// latest point in program execution where the object of type T
-// can be created.
-// Thus, any call to instance() will auto-magically result in a call to
-// instance() before main(), unless already present.
-// Furthermore, since the instance() function contains the object, instead
-// of the singleton_default class containing a static instance of the
-// object, that object is guaranteed to be constructed (at the latest) in
-// the first call to instance(). This permits calls to instance() from
-// static code, even if that code is called before the file-scope objects
-// in this file have been initialized.
-
namespace boost {
namespace details {
namespace pool {
-// T must be: no-throw default constructible and no-throw destructible
+// T must be: no-throw default constructible and no-throw destructible.
template <typename T>
+/*!< \tparam T type which must be a singleton.
+\pre T must be no-throw default constructible and no-throw destructible.
+*/
struct singleton_default
{
private:
struct object_creator
{
- // This constructor does nothing more than ensure that instance()
- // is called before main() begins, thus creating the static
- // T object before multithreading race issues can come up.
- object_creator() { singleton_default<T>::instance(); }
- inline void do_nothing() const { }
+ object_creator()
+ { //! This constructor does nothing more than ensure that instance()
+ //! is called before main() begins, thus creating the static
+ //! T object before multithreading race issues can come up.
+ singleton_default<T>::instance();
+ }
+ inline void do_nothing() const
+ {
+ }
};
static object_creator create_object;
@@ -76,7 +100,7 @@
// If, at any point (in user code), singleton_default<T>::instance()
// is called, then the following function is instantiated.
static object_type & instance()
- {
+ { //! \returns a reference of type T& to the singleton instance.
// This is the object that we return a reference to.
// It is guaranteed to be created before main() begins because of
// the next line.
@@ -99,7 +123,7 @@
} // namespace boost
-// The following code might be put into some Boost.Config header in a later revision
+// The following code might be put into some Boost.Config header in a later revision.
#ifdef __BORLANDC__
# pragma option pop
#endif
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