Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

Safe hooks

Features of the safe mode
Configuring safe-mode assertions

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.

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>

PrevUpHomeNext