| Home | Libraries | People | FAQ | More

## Safe hooks

### 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>