King_DuckZ/Loki
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

more doxygen documentation, modules added

Browse source 
git-svn-id: svn://svn.code.sf.net/p/loki-lib/code/trunk@347 7ec92016-0320-0410-acc4-a06ded1c099a
This commit is contained in:
syntheticpp 2005-11-02 20:01:11 +00:00
parent cff0fad314
commit 76309d2b5c
4 changed files with 196 additions and 121 deletions
Download patch file Download diff file Expand all files Collapse all files

218
include/loki/Singleton.h
View file

@ -30,6 +30,12 @@
#define LOKI_C_CALLING_CONVENTION_QUALIFIER #define LOKI_C_CALLING_CONVENTION_QUALIFIER
#endif #endif
/// \defgroup SingletonGroup Singleton
/// \defgroup CreationGroup Creation policies
/// \ingroup SingletonGroup
/// \defgroup LifetimeGroup Lifetime policies
/// \ingroup SingletonGroup
namespace Loki namespace Loki
{ {
@ -101,11 +107,11 @@ namespace Loki
} // namespace Private } // namespace Private
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
// function template SetLongevity /// \ingroup LifetimeGroup
// Assigns an object a longevity; ensures ordered destructions of objects ///
// registered thusly during the exit sequence of the application /// Assigns an object a longevity; ensures ordered destructions of objects
/// registered thusly during the exit sequence of the application
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
template <typename T, typename Destroyer> template <typename T, typename Destroyer>
void SetLongevity(T* pDynObject, unsigned int longevity, void SetLongevity(T* pDynObject, unsigned int longevity,
Destroyer d) Destroyer d)
@ -148,11 +154,12 @@ namespace Loki
} }
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
// class template CreateUsingNew /// \struct CreateUsingNew
// Implementation of the CreationPolicy used by SingletonHolder ///
// Creates objects using a straight call to the new operator /// \ingroup CreationGroup
/// Implementation of the CreationPolicy used by SingletonHolder
/// Creates objects using a straight call to the new operator
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
template <class T> struct CreateUsingNew template <class T> struct CreateUsingNew
{ {
static T* Create() static T* Create()
@ -162,13 +169,15 @@ namespace Loki
{ delete p; } { delete p; }
}; };
////////////////////////////////////////////////////////////////////////////////
// class template CreateUsingNew
// Implementation of the CreationPolicy used by SingletonHolder
// Creates objects using a call to std::malloc, followed by a call to the
// placement new operator
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// \struct CreateUsingMalloc
///
/// \ingroup CreationGroup
/// Implementation of the CreationPolicy used by SingletonHolder
/// Creates objects using a call to std::malloc, followed by a call to the
/// placement new operator
////////////////////////////////////////////////////////////////////////////////
template <class T> struct CreateUsingMalloc template <class T> struct CreateUsingMalloc
{ {
static T* Create() static T* Create()
@ -185,15 +194,17 @@ namespace Loki
} }
}; };
////////////////////////////////////////////////////////////////////////////////
// class template CreateStatic
// Implementation of the CreationPolicy used by SingletonHolder
// Creates an object in static memory
// Implementation is slightly nonportable because it uses the MaxAlign trick
// (an union of all types to ensure proper memory alignment). This trick is
// nonportable in theory but highly portable in practice.
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// \struct CreateStatic
///
/// \ingroup CreationGroup
/// Implementation of the CreationPolicy used by SingletonHolder
/// Creates an object in static memory
/// Implementation is slightly nonportable because it uses the MaxAlign trick
/// (an union of all types to ensure proper memory alignment). This trick is
/// nonportable in theory but highly portable in practice.
////////////////////////////////////////////////////////////////////////////////
template <class T> struct CreateStatic template <class T> struct CreateStatic
{ {
@ -234,12 +245,13 @@ namespace Loki
}; };
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
// class template DefaultLifetime /// \struct DefaultLifetime
// Implementation of the LifetimePolicy used by SingletonHolder ///
// Schedules an object's destruction as per C++ rules /// \ingroup LifetimeGroup
// Forwards to std::atexit /// Implementation of the LifetimePolicy used by SingletonHolder
/// Schedules an object's destruction as per C++ rules
/// Forwards to std::atexit
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
template <class T> template <class T>
struct DefaultLifetime struct DefaultLifetime
{ {
@ -251,12 +263,13 @@ namespace Loki
}; };
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
// class template PhoenixSingleton /// \struct PhoenixSingleton
// Implementation of the LifetimePolicy used by SingletonHolder ///
// Schedules an object's destruction as per C++ rules, and it allows object /// \ingroup LifetimeGroup
// recreation by not throwing an exception from OnDeadReference /// Implementation of the LifetimePolicy used by SingletonHolder
/// Schedules an object's destruction as per C++ rules, and it allows object
/// recreation by not throwing an exception from OnDeadReference
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
template <class T> template <class T>
class PhoenixSingleton class PhoenixSingleton
{ {
@ -287,19 +300,23 @@ namespace Loki
#endif #endif
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
// class template DeletableSingleton /// Copyright (c) 2004 by Curtis Krauskopf - curtis\decompile.com
// Copyright (c) 2004 by Curtis Krauskopf - curtis@decompile.com ///
// /// \struct DeletableSingleton
// A DeletableSingleton allows the instantiated singleton to be ///
// destroyed at any time. The singleton can be reinstantiated at /// \ingroup LifetimeGroup
// any time, even during program termination. ///
// If the singleton exists when the program terminates, it will /// A DeletableSingleton allows the instantiated singleton to be
// be automatically deleted. /// destroyed at any time. The singleton can be reinstantiated at
// /// any time, even during program termination.
// The singleton can be deleted manually: /// If the singleton exists when the program terminates, it will
// DeletableSingleton<MyClass>::GracefulDelete(); /// be automatically deleted.
///
/// \par Usage:
/// The singleton can be deleted manually:
///
/// DeletableSingleton<MyClass>::GracefulDelete();
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
template <class T> template <class T>
class DeletableSingleton class DeletableSingleton
{ {
@ -321,7 +338,7 @@ namespace Loki
static void OnDeadReference() static void OnDeadReference()
{ {
} }
/// delete singleton object manually
static void GracefulDelete() static void GracefulDelete()
{ {
if (isDead) if (isDead)
@ -371,13 +388,14 @@ namespace Loki
} }
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
// class template SingletonWithLongevity /// \struct SingletonWithLongevity
// Implementation of the LifetimePolicy used by SingletonHolder ///
// Schedules an object's destruction in order of their longevities /// \ingroup LifetimeGroup
// Assumes a visible function GetLongevity(T*) that returns the longevity of the /// Implementation of the LifetimePolicy used by SingletonHolder
// object /// Schedules an object's destruction in order of their longevities
/// Assumes a visible function GetLongevity(T*) that returns the longevity of the
/// object.
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
template <class T> template <class T>
class SingletonWithLongevity class SingletonWithLongevity
{ {
@ -393,11 +411,12 @@ namespace Loki
}; };
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
// class template NoDestroy /// \struct NoDestroy
// Implementation of the LifetimePolicy used by SingletonHolder ///
// Never destroys the object /// \ingroup LifetimeGroup
/// Implementation of the LifetimePolicy used by SingletonHolder
/// Never destroys the object
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
template <class T> template <class T>
struct NoDestroy struct NoDestroy
{ {
@ -408,12 +427,6 @@ namespace Loki
{} {}
}; };
////////////////////////////////////////////////////////////////////////////////
// DieOrder lifetime policy:
// Policy to handle lifetime dependencies
////////////////////////////////////////////////////////////////////////////////
template <unsigned int Longevity, class T> template <unsigned int Longevity, class T>
class SingletonFixedLongevity class SingletonFixedLongevity
{ {
@ -428,39 +441,49 @@ namespace Loki
{ throw std::logic_error("Dead Reference Detected"); } { throw std::logic_error("Dead Reference Detected"); }
}; };
////////////////////////////////////////////////////////////////////////////////
/// \struct DieOrder
///
/// \ingroup LifetimeGroup
/// Lifetime policy to handle lifetime dependencies
////////////////////////////////////////////////////////////////////////////////
struct DieOrder struct DieOrder
{ {
/// \struct Last
/// Die after the singleton with the DieOrder::First lifetime
template <class T> template <class T>
struct Last : public SingletonFixedLongevity<0xFFFFFFFF ,T> struct Last : public SingletonFixedLongevity<0xFFFFFFFF ,T>
{}; {};
/// \struct First
/// Die before the singleton with the DieOrder::Last lifetime
template <class T> template <class T>
struct First : public SingletonFixedLongevity<0xFFFFFFFF-1,T> struct First : public SingletonFixedLongevity<0xFFFFFFFF-1,T>
{}; {};
}; };
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
// FollowIntoDeath lifetime policy: followers will die after the master dies /// \struct FollowIntoDeath
// Followers will not die, if ///
// - master never dies (NoDestroy policy) /// \ingroup LifetimeGroup
// - master never created ///
// - master dies not in the function registered with atexit /// Lifetime policyfor the SingletonHolder tempalte.
// - master dies not by a call of a the atexit registerd function /// Followers will die after the master dies Followers will not die, if
// (DeletableSingleton::GreathFullDeath) /// - master never dies (NoDestroy policy)
// /// - master never created
// Usage: /// - master dies not in the function registered with atexit
// Lifetime of the master singleton e.g. with a Master class: /// - master dies not by a call of a the atexit registerd function (DeletableSingleton::GreathFullDeath)
// SingletonHolder<Master, ///
// FollowIntoDeath::With<DefaultLifetime>::AsMasterLifetime> /// \par Usage:
// MasterSingleton; ///
// /// Lifetime of the master singleton, e.g. with a M class:
// Lifetime of the follower singleton e.g. with a Follower class: /// SingletonHolder<M,FollowIntoDeath::With<DefaultLifetime>::AsMasterLifetime> MasterSingleton;
// SingletonHolder<Follower,CreateUsingNew, ///
// FollowIntoDeath::AfterMaster<MasterSingleton>::IsDestroyed> /// Lifetime of the follower singleton, e.g. with a F class:
// FollowerSingleton ///
/// SingletonHolder<F,CreateUsingNew,FollowIntoDeath::AfterMaster<MasterSingleton>::IsDestroyed>FollowerSingleton
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
class FollowIntoDeath
struct FollowIntoDeath
{ {
template<class T> template<class T>
class Followers class Followers
@ -495,10 +518,16 @@ namespace Loki
} }
}; };
public:
/// \struct With
/// Template for the master
/// \param Lifetime Lifetime policy for the master
template<template <class> class Lifetime> template<template <class> class Lifetime>
struct With struct With
{ {
/// \struct AsMasterLifetime
/// Policy for master
template<class Master> template<class Master>
struct AsMasterLifetime struct AsMasterLifetime
{ {
@ -521,9 +550,14 @@ namespace Loki
}; };
}; };
/// \struct AfterMaster
/// Template for the follower
/// \param Master Master to follow into death
template<class Master> template<class Master>
struct AfterMaster struct AfterMaster
{ {
/// \struct IsDestroyed
/// Policy for followers
template<class F> template<class F>
struct IsDestroyed struct IsDestroyed
{ {
@ -545,13 +579,21 @@ namespace Loki
FollowIntoDeath::Followers<T>::followers_ = 0; FollowIntoDeath::Followers<T>::followers_ = 0;
////////////////////////////////////////////////////////////////////////////////
// class template SingletonHolder
// Provides Singleton amenities for a type T
// To protect that type from spurious instantiations, you have to protect it
// yourself.
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// \class SingletonHolder
///
/// \ingroup SingletonGroup
///
/// Provides Singleton amenities for a type T
/// To protect that type from spurious instantiations,
/// you have to protect it yourself.
///
/// \param CreationPolicy Creation policy, default: CreateUsingNew
/// \param LifetimePolicy Lifetime policy, default: DefaultLifetime,
/// \param ThreadingModel Threading policy,
/// default: LOKI_DEFAULT_THREADING_NO_OBJ_LEVEL
////////////////////////////////////////////////////////////////////////////////
template template
< <
typename T, typename T,
@ -562,6 +604,8 @@ namespace Loki
class SingletonHolder class SingletonHolder
{ {
public: public:
/// Returns a reference to singleton object
static T& Instance(); static T& Instance();
private: private:

19
include/loki/SmallObj.h
View file

@ -51,11 +51,17 @@
#undef LOKI_SMALL_OBJECT_USE_NEW_ARRAY #undef LOKI_SMALL_OBJECT_USE_NEW_ARRAY
#endif #endif
/// \defgroup SmallObjectGroup Small objects
///
/// \defgroup SmallObjectGroupInternal Internals
/// \ingroup SmallObjectGroup
namespace Loki namespace Loki
{ {
class FixedAllocator; class FixedAllocator;
/** @class SmallObjAllocator /** @class SmallObjAllocator
@ingroup SmallObjectGroupInternal
Manages pool of fixed-size allocators. Manages pool of fixed-size allocators.
Designed to be a non-templated base class of AllocatorSingleton so that Designed to be a non-templated base class of AllocatorSingleton so that
implementation details can be safely hidden in the source code file. implementation details can be safely hidden in the source code file.
@ -161,6 +167,7 @@ namespace Loki
/** @class AllocatorSingleton /** @class AllocatorSingleton
@ingroup SmallObjectGroupInternal
This template class is derived from This template class is derived from
SmallObjAllocator in order to pass template arguments into it, and still SmallObjAllocator in order to pass template arguments into it, and still
have a default constructor for the singleton. Each instance is a unique have a default constructor for the singleton. Each instance is a unique
@ -172,7 +179,7 @@ namespace Loki
clients to use the new_handler without having the name of the new_handler clients to use the new_handler without having the name of the new_handler
function show up in classes derived from SmallObject or SmallValueObject. function show up in classes derived from SmallObject or SmallValueObject.
Thus, the only functions in the allocator which show up in SmallObject or Thus, the only functions in the allocator which show up in SmallObject or
SmallValueObject inheritance heierarchies are the new and delete SmallValueObject inheritance hierarchies are the new and delete
operators. operators.
*/ */
template template
@ -274,6 +281,7 @@ namespace Loki
/** @class SmallObjectBase /** @class SmallObjectBase
@ingroup SmallObjectGroupInternal
Base class for small object allocation classes. Base class for small object allocation classes.
The shared implementation of the new and delete operators are here instead The shared implementation of the new and delete operators are here instead
of being duplicated in both SmallObject or SmallValueObject. This class of being duplicated in both SmallObject or SmallValueObject. This class
@ -457,7 +465,8 @@ namespace Loki
}; // end class SmallObjectBase }; // end class SmallObjectBase
/** @class /** @class SmallObject
@ingroup SmallObjectGroup
SmallObject Base class for polymorphic small objects, offers fast SmallObject Base class for polymorphic small objects, offers fast
allocations & deallocations. Destructor is virtual and public. Default allocations & deallocations. Destructor is virtual and public. Default
constructor is trivial. Copy-constructor and copy-assignment operator are constructor is trivial. Copy-constructor and copy-assignment operator are
@ -490,7 +499,8 @@ namespace Loki
}; // end class SmallObject }; // end class SmallObject
/** @class /** @class SmallValueObject
@ingroup SmallObjectGroup
SmallValueObject Base class for small objects with value-type SmallValueObject Base class for small objects with value-type
semantics - offers fast allocations & deallocations. Destructor is semantics - offers fast allocations & deallocations. Destructor is
non-virtual, inline, and protected to prevent unintentional destruction non-virtual, inline, and protected to prevent unintentional destruction
@ -525,6 +535,9 @@ namespace Loki
// Nov. 26, 2004: re-implemented by Rich Sposato. // Nov. 26, 2004: re-implemented by Rich Sposato.
// //
// $Log$ // $Log$
// Revision 1.20 2005/11/02 20:01:10 syntheticpp
// more doxygen documentation, modules added
//
// Revision 1.19 2005/11/01 11:11:52 syntheticpp // Revision 1.19 2005/11/01 11:11:52 syntheticpp
// add lifetime policies to manage singleton lifetime dependencies: FollowIntoDeath and DieOrder. Change SmallObject.h to avoid memory leaks by default // add lifetime policies to manage singleton lifetime dependencies: FollowIntoDeath and DieOrder. Change SmallObject.h to avoid memory leaks by default
// //

41
include/loki/Threads.h
View file

@ -11,6 +11,9 @@
// $Header$ // $Header$
/*!
@defgroup ThreadingGroup Threading
*/
#if defined(LOKI_CLASS_LEVEL_THREADING) || defined(LOKI_OBJECT_LEVEL_THREADING) #if defined(LOKI_CLASS_LEVEL_THREADING) || defined(LOKI_OBJECT_LEVEL_THREADING)
@ -39,12 +42,14 @@
namespace Loki namespace Loki
{ {
////////////////////////////////////////////////////////////////////////////////
// class template SingleThreaded
// Implementation of the ThreadingModel policy used by various classes
// Implements a single-threaded model; no synchronization
////////////////////////////////////////////////////////////////////////////////
/*!
\class SingleThreaded
\ingroup ThreadingGroup
Implementation of the ThreadingModel policy used by various classes
Implements a single-threaded model; no synchronization
*/
template <class Host> template <class Host>
class SingleThreaded class SingleThreaded
{ {
@ -145,12 +150,14 @@ namespace Loki
#if defined(_WINDOWS_) || defined(_WINDOWS_H) || defined(_PTHREAD_H) #if defined(_WINDOWS_) || defined(_WINDOWS_H) || defined(_PTHREAD_H)
//////////////////////////////////////////////////////////////////////////////// /*!
// class template ObjectLevelLockable \class ObjectLevelLockable
// Implementation of the ThreadingModel policy used by various classes \ingroup ThreadingGroup
// Implements a object-level locking scheme
////////////////////////////////////////////////////////////////////////////////
class template ObjectLevelLockable
Implementation of the ThreadingModel policy used by various classes
Implements a object-level locking scheme
*/
template <class Host> template <class Host>
class ObjectLevelLockable class ObjectLevelLockable
{ {
@ -215,12 +222,13 @@ namespace Loki
#endif #endif
//////////////////////////////////////////////////////////////////////////////// /*!
// class template ClassLevelLockable \class ClassLevelLockable
// Implementation of the ThreadingModel policy used by various classes \ingroup ThreadingGroup
// Implements a class-level locking scheme
////////////////////////////////////////////////////////////////////////////////
Implementation of the ThreadingModel policy used by various classes
Implements a class-level locking scheme
*/
template <class Host> template <class Host>
class ClassLevelLockable class ClassLevelLockable
{ {
@ -314,6 +322,9 @@ namespace Loki
#endif #endif
// $Log$ // $Log$
// Revision 1.17 2005/11/02 20:01:10 syntheticpp
// more doxygen documentation, modules added
//
// Revision 1.16 2005/10/30 14:03:23 syntheticpp // Revision 1.16 2005/10/30 14:03:23 syntheticpp
// replace tabs space // replace tabs space
// //

13
src/SmallObj.cpp
View file

@ -36,6 +36,7 @@ namespace Loki
{ {
/** @struct Chunk /** @struct Chunk
@ingroup SmallObjectGroupInternal
Contains info about each allocated Chunk - which is a collection of Contains info about each allocated Chunk - which is a collection of
contiguous blocks. Each block is the same size, as specified by the contiguous blocks. Each block is the same size, as specified by the
FixedAllocator. The number of blocks in a Chunk depends upon page size. FixedAllocator. The number of blocks in a Chunk depends upon page size.
@ -128,6 +129,7 @@ namespace Loki
}; };
/** @class FixedAllocator /** @class FixedAllocator
@ingroup SmallObjectGroupInternal
Offers services for allocating fixed-sized objects. It has a container Offers services for allocating fixed-sized objects. It has a container
of "containers" of fixed-size blocks. The outer container has all the of "containers" of fixed-size blocks. The outer container has all the
Chunks. The inner container is a Chunk which owns some blocks. Chunks. The inner container is a Chunk which owns some blocks.
@ -697,8 +699,8 @@ void FixedAllocator::DoDeallocate(void* p)
} }
// GetOffset ------------------------------------------------------------------ // GetOffset ------------------------------------------------------------------
/// @ingroup SmallObjectGroupInternal
/// Calculates index into array where a FixedAllocator of numBytes is located. /// Calculates index into array where a FixedAllocator of numBytes is located.
inline std::size_t GetOffset( std::size_t numBytes, std::size_t alignment ) inline std::size_t GetOffset( std::size_t numBytes, std::size_t alignment )
{ {
const std::size_t alignExtra = alignment-1; const std::size_t alignExtra = alignment-1;
@ -706,7 +708,8 @@ inline std::size_t GetOffset( std::size_t numBytes, std::size_t alignment )
} }
// DefaultAllocator ----------------------------------------------------------- // DefaultAllocator -----------------------------------------------------------
/** Calls the default allocator when SmallObjAllocator decides not to handle a /** @ingroup SmallObjectGroupInternal
Calls the default allocator when SmallObjAllocator decides not to handle a
request. SmallObjAllocator calls this if the number of bytes is bigger than request. SmallObjAllocator calls this if the number of bytes is bigger than
the size which can be handled by any FixedAllocator. the size which can be handled by any FixedAllocator.
@param doThrow True if this function should throw an exception, or false if it @param doThrow True if this function should throw an exception, or false if it
@ -726,7 +729,8 @@ void * DefaultAllocator( std::size_t numBytes, bool doThrow )
} }
// DefaultDeallocator --------------------------------------------------------- // DefaultDeallocator ---------------------------------------------------------
/** Calls default deallocator when SmallObjAllocator decides not to handle a /** @ingroup SmallObjectGroupInternal
Calls default deallocator when SmallObjAllocator decides not to handle a
request. The default deallocator could be the global delete operator or the request. The default deallocator could be the global delete operator or the
free function. The free function is the preferred default deallocator since free function. The free function is the preferred default deallocator since
it matches malloc which is the preferred default allocator. SmallObjAllocator it matches malloc which is the preferred default allocator. SmallObjAllocator
@ -882,6 +886,9 @@ void SmallObjAllocator::Deallocate( void * p )
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
// $Log$ // $Log$
// Revision 1.16 2005/11/02 20:01:11 syntheticpp
// more doxygen documentation, modules added
//
// Revision 1.15 2005/10/26 00:50:44 rich_sposato // Revision 1.15 2005/10/26 00:50:44 rich_sposato
// Minor changes to documentation comments. // Minor changes to documentation comments.
// //