update documentation due to the new lifetime policies
git-svn-id: svn://svn.code.sf.net/p/loki-lib/code/trunk@360 7ec92016-0320-0410-acc4-a06ded1c099a
This commit is contained in:
syntheticpp
parent
a1b035fd15
commit
a966dc9aff
1 changed files with 84 additions and 42 deletions
|
|
@ -56,20 +56,20 @@ namespace Loki
|
||||||
namespace LongevityLifetime
|
namespace LongevityLifetime
|
||||||
{
|
{
|
||||||
/** @struct DieAsSmallObjectParent
|
/** @struct DieAsSmallObjectParent
|
||||||
@ingroup SmallObjectGroup
|
@ingroup SmallObjectGroup
|
||||||
Lifetime policy to manage lifetime dependencies of
|
Lifetime policy to manage lifetime dependencies of
|
||||||
SmallObject base and child classes.
|
SmallObject base and child classes.
|
||||||
The Base class should have this lifetime
|
The Base class should have this lifetime
|
||||||
*/
|
*/
|
||||||
template <class T>
|
template <class T>
|
||||||
struct DieAsSmallObjectParent : DieLast<T> {};
|
struct DieAsSmallObjectParent : DieLast<T> {};
|
||||||
|
|
||||||
/** @struct DieAsSmallObjectChild
|
/** @struct DieAsSmallObjectChild
|
||||||
@ingroup SmallObjectGroup
|
@ingroup SmallObjectGroup
|
||||||
Lifetime policy to manage lifetime dependencies of
|
Lifetime policy to manage lifetime dependencies of
|
||||||
SmallObject base and child classes.
|
SmallObject base and child classes.
|
||||||
The Child class should have this lifetime
|
The Child class should have this lifetime
|
||||||
*/
|
*/
|
||||||
template <class T>
|
template <class T>
|
||||||
struct DieAsSmallObjectChild : DieDirectlyBeforeLast<T> {};
|
struct DieAsSmallObjectChild : DieDirectlyBeforeLast<T> {};
|
||||||
|
|
||||||
|
|
@ -298,42 +298,81 @@ namespace Loki
|
||||||
|
|
||||||
|
|
||||||
/** @class SmallObjectBase
|
/** @class SmallObjectBase
|
||||||
@ingroup SmallObjectGroupInternal
|
@ingroup SmallObjectGroup
|
||||||
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, later just
|
||||||
is not meant to be used directly by clients, or derived from by clients.
|
called Small-Objects. This class is not meant to be used directly by clients,
|
||||||
Class has no data members so compilers can use Empty-Base-Optimization.
|
or derived from by clients. Class has no data members so compilers can
|
||||||
|
use Empty-Base-Optimization.
|
||||||
|
|
||||||
@par Singleton Lifetime Policies and Small-Object Allocator
|
@par Lifetime Policy
|
||||||
At this time, the only Singleton Lifetime policies recommended for
|
|
||||||
use with the Small-Object Allocator are Loki::SingletonWithLongevity and
|
|
||||||
Loki::NoDestroy. The Loki::DefaultLifetime and Loki::PhoenixSingleton
|
|
||||||
policies are *not* recommended since they can cause the allocator to be
|
|
||||||
destroyed and release memory for singletons which inherit from either
|
|
||||||
SmallObject or SmallValueObject. The default is Loki::NoDestroy to
|
|
||||||
insure that memory is never released before the object using that
|
|
||||||
memory is destroyed. Loki::SingletonWithLongevity can also insure that
|
|
||||||
no memory is released before the owning object is destroyed, and also
|
|
||||||
insure that any memory controlled by a Small-Object Allocator is
|
|
||||||
released.
|
|
||||||
|
|
||||||
@par Small Singletons and Lifetime Policies
|
The SmallObjectBase template needs a lifetime policy because it owns
|
||||||
If you a singleton is derived from SmallValueObject or SmallObject, you
|
a singleton of SmallObjAllocator which does all the low level functions.
|
||||||
have to use compatible lifetime policies for both the singleton and the
|
When using a Small-Object in combination with the SingletonHolder template
|
||||||
allocator. The 3 possible options are:
|
you have to choose two lifetimes, that of the Small-Object and that of
|
||||||
- They may both be Loki::NoDestroy. Since neither is ever destroyed, the
|
the singleton. The rule is: The Small-Object lifetime must be greater than
|
||||||
destruction order does not matter.
|
the lifetime of the singleton hosting the Small-Object. Violating this rule
|
||||||
- They may both be Loki::SingletonWithLongevity as long as the longevity
|
results in a crash on exit, because the hosting singleton tries to delete
|
||||||
level for the singleton is lower than that for the allocator. This is
|
the Small-Object which is then already destroyed.
|
||||||
why the allocator's GetLongevity function returns the highest value.
|
|
||||||
- The singleton may use Loki::SingletonWithLongevity, and the allocator
|
The lifetime policies recommended for use with Small-Objects hosted
|
||||||
may use Loki::NoDestroy. This is why the allocator's default policy is
|
by a SingletonHolder template are
|
||||||
Loki::NoDestroy.
|
- LongevityLifetime::DieAsSmallObjectParent / LongevityLifetime::DieAsSmallObjectChild
|
||||||
You should *not* use Loki::NoDestroy for the singleton, and then use
|
- SingletonWithLongevity
|
||||||
Loki::SingletonWithLongevity for the allocator. This causes the allocator
|
- FollowIntoDeath (not supported by MSVC 7.1)
|
||||||
to be destroyed and release the memory for the singleton while the
|
- NoDestroy
|
||||||
singleton is still alive.
|
|
||||||
|
The default lifetime of Small-Objects is
|
||||||
|
LongevityLifetime::DieAsSmallObjectParent to
|
||||||
|
insure that memory is not released before a object with the lifetime
|
||||||
|
LongevityLifetime::DieAsSmallObjectChild using that
|
||||||
|
memory is destroyed. The LongevityLifetime::DieAsSmallObjectParent
|
||||||
|
lifetime has the highest possible value of a SetLongevity lifetime, so
|
||||||
|
you can use it in combination with your own lifetime not having also
|
||||||
|
the highest possible value.
|
||||||
|
|
||||||
|
The DefaultLifetime and PhoenixSingleton policies are *not* recommended
|
||||||
|
since they can cause the allocator to be destroyed and release memory
|
||||||
|
for singletons hosting a object which inherit from either SmallObject
|
||||||
|
or SmallValueObject.
|
||||||
|
|
||||||
|
@par Lifetime usage
|
||||||
|
|
||||||
|
- LongevityLifetime: The Small-Object has
|
||||||
|
LongevityLifetime::DieAsSmallObjectParent policy and the Singleton
|
||||||
|
hosting the Small-Object has LongevityLifetime::DieAsSmallObjectChild.
|
||||||
|
The child lifetime has a hard coded SetLongevity lifetime which is
|
||||||
|
shorter than the lifetime of the parent, thus the child dies
|
||||||
|
before the parent.
|
||||||
|
|
||||||
|
- Both Small-Object and Singleton use SingletonWithLongevity policy.
|
||||||
|
The longevity level for the singleton must be lower than that for the
|
||||||
|
Small-Object. This is why the AllocatorSingleton's GetLongevity function
|
||||||
|
returns the highest value.
|
||||||
|
|
||||||
|
- FollowIntoDeath lifetime: The Small-Object has
|
||||||
|
FollowIntoDeath::With<LIFETIME>::AsMasterLiftime
|
||||||
|
policy and the Singleton has
|
||||||
|
FollowIntoDeath::AfterMaster<MASTERSINGLETON>::IsDestroyed policy,
|
||||||
|
where you could choose the LIFETIME.
|
||||||
|
|
||||||
|
- Both Small-Object and Singleton use NoDestroy policy.
|
||||||
|
Since neither is ever destroyed, the destruction order does not matter.
|
||||||
|
Note: yow will get memory leaks!
|
||||||
|
|
||||||
|
- The Small-Object has NoDestroy policy but the Singleton has
|
||||||
|
SingletonWithLongevity policy. Note: yow will get memory leaks!
|
||||||
|
|
||||||
|
|
||||||
|
You should *not* use NoDestroy for the singleton, and then use
|
||||||
|
SingletonWithLongevity for the Small-Object.
|
||||||
|
|
||||||
|
@par Examples:
|
||||||
|
|
||||||
|
- test/SmallObj/SmallSingleton.cpp
|
||||||
|
- test/Singleton/Dependencies.cpp
|
||||||
*/
|
*/
|
||||||
template
|
template
|
||||||
<
|
<
|
||||||
|
|
@ -552,6 +591,9 @@ namespace Loki
|
||||||
// Nov. 26, 2004: re-implemented by Rich Sposato.
|
// Nov. 26, 2004: re-implemented by Rich Sposato.
|
||||||
//
|
//
|
||||||
// $Log$
|
// $Log$
|
||||||
|
// Revision 1.23 2005/11/13 16:51:22 syntheticpp
|
||||||
|
// update documentation due to the new lifetime policies
|
||||||
|
//
|
||||||
// Revision 1.22 2005/11/07 12:06:43 syntheticpp
|
// Revision 1.22 2005/11/07 12:06:43 syntheticpp
|
||||||
// change lifetime policy DieOrder to a msvc7.1 compilable version. Make this the default lifetime for SmallObject
|
// change lifetime policy DieOrder to a msvc7.1 compilable version. Make this the default lifetime for SmallObject
|
||||||
//
|
//
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue