1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Safe hooks</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../intrusive.html" title="Chapter 13. Boost.Intrusive">
<link rel="prev" href="presenting_containers.html" title="Presenting Boost.Intrusive containers">
<link rel="next" href="auto_unlink_hooks.html" title="Auto-unlink hooks">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="presenting_containers.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../intrusive.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="auto_unlink_hooks.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="intrusive.safe_hook"></a><a class="link" href="safe_hook.html" title="Safe hooks">Safe hooks</a>
</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="safe_hook.html#intrusive.safe_hook.features">Features of the safe mode</a></span></dt>
<dt><span class="section"><a href="safe_hook.html#intrusive.safe_hook.configuring">Configuring safe-mode
assertions</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="intrusive.safe_hook.features"></a><a class="link" href="safe_hook.html#intrusive.safe_hook.features" title="Features of the safe mode">Features of the safe mode</a>
</h3></div></div></div>
<p>
<span class="bold"><strong>Boost.Intrusive</strong></span> hooks can be configured
to operate in safe-link mode. The safe mode is activated by default, but
it can be also explicitly activated:
</p>
<pre class="programlisting"><span class="comment">//Configuring the safe mode explicitly</span>
<span class="keyword">class</span> <span class="identifier">Foo</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">list_base_hook</span><span class="special"><</span> <span class="identifier">link_mode</span><span class="special"><</span><span class="identifier">safe_link</span><span class="special">></span> <span class="special">></span>
<span class="special">{};</span>
</pre>
<p>
With the safe mode the user can detect if the object is actually inserted
in a container without any external reference. Let's review the basic features
of the safe mode:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
Hook's constructor puts the hook in a well-known default state.
</li>
<li class="listitem">
Hook's destructor checks if the hook is in the well-known default state.
If not, an assertion is raised.
</li>
<li class="listitem">
Every time an object is inserted in the intrusive container, the container
checks if the hook is in the well-known default state. If not, an assertion
is raised.
</li>
<li class="listitem">
Every time an object is being erased from the intrusive container, the
container puts the erased object in the well-known default state.
</li>
</ul></div>
<p>
With these features, without any external reference the user can know if
the object has been inserted in a container by calling the <code class="computeroutput"><span class="identifier">is_linked</span><span class="special">()</span></code>
member function. If the object is not actually inserted in a container, the
hook is in the default state, and if it is inserted in a container, the hook
is not in the default state.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="intrusive.safe_hook.configuring"></a><a class="link" href="safe_hook.html#intrusive.safe_hook.configuring" title="Configuring safe-mode assertions">Configuring safe-mode
assertions</a>
</h3></div></div></div>
<p>
By default, all safe-mode assertions raised by <span class="bold"><strong>Boost-Intrusive</strong></span>
hooks and containers in are implemented using <code class="computeroutput"><span class="identifier">BOOST_ASSERT</span></code>,
which can be configured by the user. See <a href="http://www.boost.org/libs/utility/assert.html" target="_top">http://www.boost.org/libs/utility/assert.html</a>
for more information about <code class="computeroutput"><span class="identifier">BOOST_ASSERT</span></code>.
</p>
<p>
<code class="computeroutput"><span class="identifier">BOOST_ASSERT</span></code> is globally
configured, so the user might want to redefine intrusive safe-mode assertions
without modifying the global <code class="computeroutput"><span class="identifier">BOOST_ASSERT</span></code>.
This can be achieved redefining the following macros:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem">
<code class="computeroutput"><span class="identifier">BOOST_INTRUSIVE_SAFE_HOOK_DEFAULT_ASSERT</span></code>:
This assertion will be used in insertion functions of the intrusive containers
to check that the hook of the value to be inserted is default constructed.
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">BOOST_INTRUSIVE_SAFE_HOOK_DESTRUCTOR_ASSERT</span></code>:
This assertion will be used in hooks' destructors to check that the hook
is in a default state.
</li>
</ul></div>
<p>
If any of these macros is not redefined, the assertion will default to <code class="computeroutput"><span class="identifier">BOOST_ASSERT</span></code>. If <code class="computeroutput"><span class="identifier">BOOST_INTRUSIVE_SAFE_HOOK_DEFAULT_ASSERT</span></code>
or <code class="computeroutput"><span class="identifier">BOOST_INTRUSIVE_SAFE_HOOK_DESTRUCTOR_ASSERT</span></code>
is defined and the programmer needs to include a file to configure that assertion,
it can define <code class="computeroutput"><span class="identifier">BOOST_INTRUSIVE_SAFE_HOOK_DESTRUCTOR_ASSERT_INCLUDE</span></code>
or <code class="computeroutput"><span class="identifier">BOOST_INTRUSIVE_SAFE_HOOK_DEFAULT_ASSERT_INCLUDE</span></code>
with the name of the file to include:
</p>
<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_INTRUSIVE_SAFE_HOOK_DESTRUCTOR_ASSERT</span> <span class="identifier">MYASSERT</span>
<span class="preprocessor">#define</span> <span class="identifier">BOOST_INTRUSIVE_SAFE_HOOK_DESTRUCTOR_ASSERT_INCLUDE</span> <span class="special"><</span><span class="identifier">myassert</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span>
</pre>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2005 Olaf Krzikalla<br>Copyright © 2006-2011 Ion Gaztanaga<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="presenting_containers.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../intrusive.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="auto_unlink_hooks.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
