Safe hooks

Features of the safe mode
Configuring safe-mode assertions

Features of the safe mode

Boost.Intrusive hooks can be configured to operate in safe-link mode. The safe mode is activated by default, but it can be also explicitly activated:

//Configuring the safe mode explicitly
class Foo : public list_base_hook< link_mode<safe_link> >
{};

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:

Hook's constructor puts the hook in a well-known default state.
Hook's destructor checks if the hook is in the well-known default state. If not, an assertion is raised.
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.
Every time an object is being erased from the intrusive container, the container puts the erased object in the well-known default state.

With these features, without any external reference the user can know if the object has been inserted in a container by calling the is_linked() 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.

Configuring safe-mode assertions

By default, all safe-mode assertions raised by Boost-Intrusive hooks and containers in are implemented using BOOST_ASSERT, which can be configured by the user. See http://www.boost.org/libs/utility/assert.html for more information about BOOST_ASSERT.

BOOST_ASSERT is globally configured, so the user might want to redefine intrusive safe-mode assertions without modifying the global BOOST_ASSERT. This can be achieved redefining the following macros:

BOOST_INTRUSIVE_SAFE_HOOK_DEFAULT_ASSERT: 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.
BOOST_INTRUSIVE_SAFE_HOOK_DESTRUCTOR_ASSERT: This assertion will be used in hooks' destructors to check that the hook is in a default state.

If any of these macros is not redefined, the assertion will default to BOOST_ASSERT. If BOOST_INTRUSIVE_SAFE_HOOK_DEFAULT_ASSERT or BOOST_INTRUSIVE_SAFE_HOOK_DESTRUCTOR_ASSERT is defined and the programmer needs to include a file to configure that assertion, it can define BOOST_INTRUSIVE_SAFE_HOOK_DESTRUCTOR_ASSERT_INCLUDE or BOOST_INTRUSIVE_SAFE_HOOK_DEFAULT_ASSERT_INCLUDE with the name of the file to include:

#define BOOST_INTRUSIVE_SAFE_HOOK_DESTRUCTOR_ASSERT          MYASSERT
#define BOOST_INTRUSIVE_SAFE_HOOK_DESTRUCTOR_ASSERT_INCLUDE <myassert.h>

Boost C++ Libraries

Safe hooks

Features of the safe mode

Configuring safe-mode assertions