[ceph.git] / ceph / src / boost / libs / serialization / doc / singleton.html

<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!--
(C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com . 
Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
http://www.boost.org/LICENSE_1_0.txt)
-->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="../../../boost.css">
<link rel="stylesheet" type="text/css" href="style.css">
<title>Serialization - singleton</title>
</head>
<body link="#0000ff" vlink="#800080">
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
  <tr> 
    <td valign="top" width="300"> 
      <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
    </td>
    <td valign="top"> 
      <h1 align="center">Serialization</h1>
      <h2 align="center"><code style="white-space: normal">singleton</code></h2>
    </td>
  </tr>
</table>
<hr>
<dl class="page-index">
  <dt><a href="#motivation">Motivation</a>
  <dt><a href="#features">Features</a>
  <dt><a href="#classinterface">Class Interface</a>
  <dt><a href="#requirements">Requirements</a>
  <dt><a href="#example">Examples</a>
  <dt><a href="#multithreading">Multi-Threading</a>
</dl>

<h3><a name="motivation">Motivation</a></h3>
The serialization library relies on the existence of a number
of static variables and tables to store information related
to runtime types.  Examples are tables which relate exported
names to types and tables which relate base classes to derived
classes.  Construction, destruction and usage of these variables
requires consideration of the following issues:
<ul>
  <li>Some static data variable and constant entries refer to others.  
  The sequence of initialization cannot be arbitrary but must be in proper
  sequence.</li>
  <li>A number of static variables aren't referred to explicitly and, without
  special precautions, will be stripped by most code optimizers</li>
  <li>Many of these variables are created by templates and special care must
  be taken to be sure that they are instantiated</li>
  <li>In a multi-threading system, its possible that these static variables
  will be accessed concurrently by separate threads.  This would create a
  race condition with unpredictabe behavior</li>
</ul>
This singleton class addresses all of the above issues.

<h3><a name="features">Features</a></h3>
This singleton implementation has the following features:
<ul>
  <li>
    Any instance will be constructed before any attempt is made to access it.</li>
  <li>
    Any instance created with a template is guaranteed to be instantiated.
  <li>
    Regardless of whether or not an instance has been explicitly
    referred to, it will not be stripped by the optimizer when the
    executable is built in release mode.
  <li>
    All instances are constructed before 
    <code style="white-space: normal">main</code> is called
    regardless of where they might be referenced within the program.
    In a multi-tasking system, this guarantees that there will be no 
    race conditions during the construction of any instance.  No
    thread locking is required to guarantee this.
  <li>
    The above implies that any <code style="white-space: normal">const</code>
    instances are thread-safe during the whole program.  Again, no
    thread locking is required.
  <li>
    If a mutable instance is created, and such an instance is modified
    after main is called in a multi-threading system, there exists
    the possibility that a race condition will occur.  The serialization
    library takes care that in the few places where a mutable
    singleton is required, it is not altered after 
    <code style="white-space: normal">main</code> is called.
    For a more general purpose usage, thread locking on this
    singleton could easily be implemented.  But as the serialization
    library didn't require it, it wasn't implemented.
</ul>

<h3><a name="classinterface">Class Interface</a></h3>
<pre><code>
namespace boost { 
namespace serialization {

template <class T>
class singleton : public boost::noncopyable
{
public:
    static const T & get_const_instance();
    static T & get_mutable_instance();
    static bool is_destroyed();
};

} // namespace serialization 
} // namespace boost
</code></pre>

<dl>

<dt><h4><pre><code>
static const T & get_const_instance();
</code></pre></h4></dt>
<dd>
Retrieve a constant reference to the singleton for this type.
</dd>

<dt><h4><pre><code>
static T & get_mutable_instance();
</code></pre></h4></dt>
<dd>
Retrieve a mutable reference to the singleton for this type.
</dd>

<dt><h4><pre><code>
static bool is_destroyed();
</code></pre></h4></dt>
<dd>
Return <code>true</code> if the destructor on this singleton has been 
called.  Otherwise, return <code>false</code>.
</dd>

</dl>

<h3><a name="requirements">Requirements</a></h3>
In order to be used as 
<a target="singleton.hpp" href = "../../../boost/serialization/singleton.hpp">
<code style="white-space: normal">
singleton&lt;T&gt;
</code>
</a>, the type T must be default constructable. 
It doesn't require static variables - though it may have them.
Since the library guarantees that only one instance of 
<a target="singleton.hpp" href = "../../../boost/serialization/singleton.hpp">
<code style="white-space: normal">
singleton&lt;T&gt;
</code>
</a> 
exists and all accesss is through the above static interface
functions, common member functions of T become
the functional equivalent of 
<code style="white-space: normal">static</code> functions.

<h3><a name="example">Examples</a></h3>
There are at least two different ways to use this class template.
Both are used in the serialization library.
<p>
The first way is illustrated by an excerpt from the file
<code style="white-space: normal"><a target="extended_type_info" href="../src/extended_type_info.cpp">extended_type_info.cpp</a></code>.
which contains the following code:

<pre><code>
typedef std::set&lt;const extended_type_info *, key_compare&gt; ktmap;
...
void
extended_type_info::key_register(const char *key) {
    ...
    result = singleton&lt;ktmap&gt;::get_mutable_instance().insert(this);
    ...
}
</code></pre>
Just by referring to the singleton instance anywhere in the program
will guarantee that one and only one instance for the specified
type (<code style="white-space: normal">ktmap</code> in this example) 
will exist throughout the program.  There is no need for any other
declaration or definition.
<p>
A second way is to use 
<a target="singleton.hpp" href = "../../../boost/serialization/singleton.hpp">
<code style="white-space: normal">
singleton&lt;T&gt;
</code> 
</a>
as one of the base classes of the type.  This is illustrated by a simplified
excerpt from
<a target="extended_type_info_typeid.hpp" href = "../../../boost/serialization/extended_type_info_typeid.hpp">
<code style="white-space: normal">
extended_type_info_typeid.hpp
</code> 
</a>

<pre><code>
template&lt;class T&gt;
class extended_type_info_typeid : 
    public detail::extended_type_info_typeid_0,
    public singleton&lt;extended_type_info_typeid&lt;const T&gt; &gt;
{
    friend class singleton&lt;extended_type_info_typeid&lt;const T&gt; &gt;;
private:
    // private constructor to inhibit any existence other than the 
    // static one.  Note: not all compilers support this !!!
    extended_type_info_typeid() :
        detail::extended_type_info_typeid_0()
    {
        type_register(typeid(T));
    }
    ~extended_type_info_typeid(){}
    ...
};
</code></pre>

This usage will permit a more natural syntax to be used:
<pre><code>
extended_type_info_typeid&lt;T&gt;::get_const_instance()
</code></pre>

Again, including one or more of the above statements anywhere
in the program will guarantee that one and only one instance
is created and referred to.

<h3><a name="multithreading">Multi-Threading</a></h3>
This singleton CAN be safely used in multi-threading applications if one
is careful follow a simple rule:
<p>
<b>Do not call get_mutable_instance when more than one thread is running!</b>
All singletons used in the serialization library follow this rule.  
In order to help detect accidental violations of this rule there
exist singleton lock/unlock functions.
<pre><code>
void boost::serialization::singleton_module::lock();
void boost::serialization::singleton_module::unlock();
bool boost::serialization::singleton_module::is_locked();
</code></pre>
In a program compiled for debug, any invocation of 
<code style="white-space: normal">get_mutable_instance()</code>
while the library is in a "locked" state will trap in an assertion.
The singleton module lock state is initialized as "unlocked" to permit
alteration of static variables before 
<code style="white-space: normal">main</code> is called. 
The <code style="white-space: normal">lock()</code> and
<code style="white-space: normal">unlock()</code> are "global"
in that they affect ALL the singletons defined by this template.
All serialization tests invoke <code style="white-space: normal">lock()</code>
at the start of the progam.  For programs compiled in release
mode these functions have no effect.

<hr>
<p><i>&copy; Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2007. 
Distributed under the Boost Software License, Version 1.0. (See
accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</i></p>
</body>
</html>
Commit	Line	Data
7c673cae FG	1	<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	2	<html>
	3	<!--
	4	(C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com .
	5	Use, modification and distribution is subject to the Boost Software
	6	License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
	7	http://www.boost.org/LICENSE_1_0.txt)
	8	-->
	9	<head>
	10	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
	11	<link rel="stylesheet" type="text/css" href="../../../boost.css">
	12	<link rel="stylesheet" type="text/css" href="style.css">
	13	<title>Serialization - singleton</title>
	14	</head>
	15	<body link="#0000ff" vlink="#800080">
	16	<table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
	17	<tr>
	18	<td valign="top" width="300">
	19	<h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
	20	</td>
	21	<td valign="top">
	22	<h1 align="center">Serialization</h1>
	23	<h2 align="center"><code style="white-space: normal">singleton</code></h2>
	24	</td>
	25	</tr>
	26	</table>
	27	<hr>
	28	<dl class="page-index">
	29	<dt><a href="#motivation">Motivation</a>
	30	<dt><a href="#features">Features</a>
	31	<dt><a href="#classinterface">Class Interface</a>
	32	<dt><a href="#requirements">Requirements</a>
	33	<dt><a href="#example">Examples</a>
	34	<dt><a href="#multithreading">Multi-Threading</a>
	35	</dl>
	36
	37	<h3><a name="motivation">Motivation</a></h3>
	38	The serialization library relies on the existence of a number
	39	of static variables and tables to store information related
	40	to runtime types. Examples are tables which relate exported
	41	names to types and tables which relate base classes to derived
	42	classes. Construction, destruction and usage of these variables
	43	requires consideration of the following issues:
	44	<ul>
	45	<li>Some static data variable and constant entries refer to others.
	46	The sequence of initialization cannot be arbitrary but must be in proper
	47	sequence.</li>
	48	<li>A number of static variables aren't referred to explicitly and, without
	49	special precautions, will be stripped by most code optimizers</li>
	50	<li>Many of these variables are created by templates and special care must
	51	be taken to be sure that they are instantiated</li>
	52	<li>In a multi-threading system, its possible that these static variables
	53	will be accessed concurrently by separate threads. This would create a
	54	race condition with unpredictabe behavior</li>
	55	</ul>
	56	This singleton class addresses all of the above issues.
	57
	58	<h3><a name="features">Features</a></h3>
	59	This singleton implementation has the following features:
	60	<ul>
	61	<li>
	62	Any instance will be constructed before any attempt is made to access it.</li>
	63	<li>
	64	Any instance created with a template is guaranteed to be instantiated.
65	<li>
66	Regardless of whether or not an instance has been explicitly
67	referred to, it will not be stripped by the optimizer when the
68	executable is built in release mode.
69	<li>
70	All instances are constructed before
71	<code style="white-space: normal">main</code> is called
72	regardless of where they might be referenced within the program.
73	In a multi-tasking system, this guarantees that there will be no
74	race conditions during the construction of any instance. No
75	thread locking is required to guarantee this.
76	<li>
77	The above implies that any <code style="white-space: normal">const</code>
78	instances are thread-safe during the whole program. Again, no
79	thread locking is required.
80	<li>
81	If a mutable instance is created, and such an instance is modified
82	after main is called in a multi-threading system, there exists
83	the possibility that a race condition will occur. The serialization
84	library takes care that in the few places where a mutable
85	singleton is required, it is not altered after
86	<code style="white-space: normal">main</code> is called.
87	For a more general purpose usage, thread locking on this
88	singleton could easily be implemented. But as the serialization
89	library didn't require it, it wasn't implemented.
90	</ul>
91
92	<h3><a name="classinterface">Class Interface</a></h3>
93	<pre><code>
94	namespace boost {
95	namespace serialization {
96
97	template <class T>
98	class singleton : public boost::noncopyable
99	{
100	public:
101	static const T & get_const_instance();
102	static T & get_mutable_instance();
103	static bool is_destroyed();
104	};
105
106	} // namespace serialization
107	} // namespace boost
108	</code></pre>
109
110	<dl>
111
112	<dt><h4><pre><code>
113	static const T & get_const_instance();
114	</code></pre></h4></dt>
115	<dd>
116	Retrieve a constant reference to the singleton for this type.
117	</dd>
118
119	<dt><h4><pre><code>
120	static T & get_mutable_instance();
121	</code></pre></h4></dt>
122	<dd>
123	Retrieve a mutable reference to the singleton for this type.
124	</dd>
125
126	<dt><h4><pre><code>
127	static bool is_destroyed();
128	</code></pre></h4></dt>
129	<dd>
130	Return <code>true</code> if the destructor on this singleton has been
131	called. Otherwise, return <code>false</code>.
132	</dd>
133
134	</dl>
135
136	<h3><a name="requirements">Requirements</a></h3>
137	In order to be used as
138	<a target="singleton.hpp" href = "../../../boost/serialization/singleton.hpp">
139	<code style="white-space: normal">
140	singleton<T>
141	</code>
142	</a>, the type T must be default constructable.
143	It doesn't require static variables - though it may have them.
144	Since the library guarantees that only one instance of
145	<a target="singleton.hpp" href = "../../../boost/serialization/singleton.hpp">
146	<code style="white-space: normal">
147	singleton<T>
148	</code>
149	</a>
150	exists and all accesss is through the above static interface
151	functions, common member functions of T become
152	the functional equivalent of
153	<code style="white-space: normal">static</code> functions.
154
155	<h3><a name="example">Examples</a></h3>
156	There are at least two different ways to use this class template.
157	Both are used in the serialization library.
158	<p>
159	The first way is illustrated by an excerpt from the file
160	<code style="white-space: normal"><a target="extended_type_info" href="../src/extended_type_info.cpp">extended_type_info.cpp</a></code>.
161	which contains the following code:
162
163	<pre><code>
164	typedef std::set<const extended_type_info *, key_compare> ktmap;
165	...
166	void
167	extended_type_info::key_register(const char *key) {
168	...
169	result = singleton<ktmap>::get_mutable_instance().insert(this);
170	...
171	}
172	</code></pre>
173	Just by referring to the singleton instance anywhere in the program
174	will guarantee that one and only one instance for the specified
175	type (<code style="white-space: normal">ktmap</code> in this example)
176	will exist throughout the program. There is no need for any other
177	declaration or definition.
178	<p>
179	A second way is to use
180	<a target="singleton.hpp" href = "../../../boost/serialization/singleton.hpp">
181	<code style="white-space: normal">
182	singleton<T>
183	</code>
184	</a>
185	as one of the base classes of the type. This is illustrated by a simplified
186	excerpt from
187	<a target="extended_type_info_typeid.hpp" href = "../../../boost/serialization/extended_type_info_typeid.hpp">
188	<code style="white-space: normal">
189	extended_type_info_typeid.hpp
190	</code>
191	</a>
192
193	<pre><code>
194	template<class T>
195	class extended_type_info_typeid :
196	public detail::extended_type_info_typeid_0,
197	public singleton<extended_type_info_typeid<const T> >
198	{
199	friend class singleton<extended_type_info_typeid<const T> >;
200	private:
201	// private constructor to inhibit any existence other than the
202	// static one. Note: not all compilers support this !!!
203	extended_type_info_typeid() :
204	detail::extended_type_info_typeid_0()
205	{
206	type_register(typeid(T));
207	}
208	~extended_type_info_typeid(){}
209	...
210	};
211	</code></pre>
212
213	This usage will permit a more natural syntax to be used:
214	<pre><code>
215	extended_type_info_typeid<T>::get_const_instance()
216	</code></pre>
217
218	Again, including one or more of the above statements anywhere
219	in the program will guarantee that one and only one instance
220	is created and referred to.
221
222	<h3><a name="multithreading">Multi-Threading</a></h3>
223	This singleton CAN be safely used in multi-threading applications if one
224	is careful follow a simple rule:
225	<p>
226	<b>Do not call get_mutable_instance when more than one thread is running!</b>
227	All singletons used in the serialization library follow this rule.
228	In order to help detect accidental violations of this rule there
229	exist singleton lock/unlock functions.
230	<pre><code>
231	void boost::serialization::singleton_module::lock();
232	void boost::serialization::singleton_module::unlock();
233	bool boost::serialization::singleton_module::is_locked();
234	</code></pre>
235	In a program compiled for debug, any invocation of
236	<code style="white-space: normal">get_mutable_instance()</code>
237	while the library is in a "locked" state will trap in an assertion.
238	The singleton module lock state is initialized as "unlocked" to permit
239	alteration of static variables before
240	<code style="white-space: normal">main</code> is called.
241	The <code style="white-space: normal">lock()</code> and
242	<code style="white-space: normal">unlock()</code> are "global"
243	in that they affect ALL the singletons defined by this template.
244	All serialization tests invoke <code style="white-space: normal">lock()</code>
245	at the start of the progam. For programs compiled in release
246	mode these functions have no effect.
247
248	<hr>
249	<p><i>© Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2007.
250	Distributed under the Boost Software License, Version 1.0. (See
251	accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
252	</i></p>
253	</body>
254	</html>