Safe hooks

| 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 explicity the safe mode
    class Foo : public list_base_hook< link_mode<safe_link> >
    {};

Thanks to the safe-mode the user can detect without any external reference, if the object is actually inserted in a container. Let's review the basic features of the safe-mode:

- Hooks' constructor puts the hook in a well-known default state.
- Hooks' destructor checks if the hook is in the well-known default state. If not, an assertion is raised.
- Every time an object is being 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 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's 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 be defaul to `BOOST_ASSERT`.