[library Boost.Intrusive [quickbook 1.3] [version 2007-06-23] [authors [Krzikalla, Olaf], [Gaztañaga, Ion]] [copyright 2005 Olaf Krzikalla, 2006-2007 Ion Gaztañaga] [purpose Intrusive containers] [license Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at [@http://www.boost.org/LICENSE_1_0.txt]) ] ] [section:introduction Introduction] [section:introduction_presenting Presenting Boost.Intrusive] [*Boost.Intrusive] is a library presenting some intrusive containers to the world of C++. Intrusive containers are special containers that offer [link boost_intrusive.performance better performance] and exception safety guarantees than non-intrusive containers (like STL containers). The performance benefits of intrusive containers makes them ideal as a building block to efficiently construct complex containers like multi-index containers or to design high performance code like memory allocation algorithms. While intrusive containers were and are widely used in C, they became more and more forgotten in C++ due to the presence of the standard containers which don't support intrusive techniques.[*Boost.Intrusive] not only reintroduces this technique to C++, but also encapsulates the implementation in STL-like interfaces. Hence anyone familiar with standard containers can easily use [*Boost.Intrusive]. [endsect] [section:introduction_building_intrusive Building Boost.Intrusive] There is no need to compile anything to use [*Boost.Intrusive], since it's a header only library. Just include your Boost header directory in your compiler include path. [endsect] [endsect] [section:intrusive_vs_nontrusive Intrusive and non-intrusive containers] [section:differences_intrusive_vs_nontrusive Differences between intrusive and non-intrusive containers] The main difference between intrusive containers and non-intrusive containers is that in C++ non-intrusive containers store [*copies] of values passed by the user. Containers use the `Allocator` template parameter to allocate the stored values: [c++] #include #include int main() { std::list myclass_list; MyClass myclass(...); myclass_list.push_back(myclass); //The stored object is different from the original object assert(&myclass != &myclass_list.front()); return 0; } To store the newly allocated copy of `myclass`, the container needs additional data: `std::list` usually allocates nodes that contain pointers to the next and previous node and the value itself. Something similar to: [c++] //A possible implementation of a std::list node class list_node { list_node *next; list_node *previous; MyClass value; }; On the other hand, an intrusive container does not store copies of passed objects, but it stores the objects themselves. The additional data needed to insert the object in the container must be provided by the object itself. For example, to insert `MyClass` in an intrusive container that implements a linked list, `MyClass` must contain the needed ['next] and ['previous] pointers: [c++] class MyClass { MyClass *next; MyClass *previous; //Other members... }; int main() { acme_intrusive_list list; MyClass myclass; list.push_back(myclass); //"myclass" object is stored in the list assert(&myclass == &list.front()); return 0; } As we can see, knowing which additional data the class should contain is not an easy task. [*Boost.Intrusive] offers several intrusive containers and an easy way to make user classes compatible with those containers. [endsect] [section:properties_of_intrusive Properties of Boost.Intrusive containers] Semantically, a [*Boost.Intrusive] container is similar to an STL container holding pointers to objects. That is, if you have an intrusive list holding objects of type `T`, then `std::list` would allow you to do quite the same operations (maintaining and navigating a set of objects of type T and types derived from it). A non-intrusive container has some limitations: * An object can only belong to one container: If you want to share an object between two containers, you either have to store multiple copies of those objects or you need to use containers of pointers: `std::list`. * The use of dynamic allocation to create copies of passed values can be a performance and size bottleneck in some applications. Normally, dynamic allocation imposes a size overhead for each allocation to store bookeeping information and a synchronization to protected concurrent allocation from different threads. * Only copies of objects are stored in non-intrusive containers. Hence copy or move constructors and copy or move assignment operators are required. Non-copyable and non-movable objects can't be stored in non-intrusive containers. * It's not possible to store a derived object in a STL-container while retaining its original type. Intrusive containers have some important advantages: * Operating with intrusive containers doesn't invoke any memory management at all. The time and size overhead associated with dynamic memory can be minimized. * Iterating an Intrusive container needs less memory accesses than the semantically equivalent container of pointers: iteration is faster. * Intrusive containers offer better exception guarantees than non-intrusive containers. In some situation intrusives containers offer a no-throw guarantee that can't be achieved with non-intrusive containers. * The computation of an iterator to an element from a pointer or reference to that element is a constant time operation (computing the position of `T*` in a `std::list` has linear complexity). * Intrusive containers offer predictability when inserting and erasing objects since no memory managed is done with intrusive containers. Memory management usually is not a predicable operation so complexity guarantees from non-intrusive containers are looser than the guarantees offered by intrusive containers. Intrusive containers have also downsides: * Each type stored in an intrusive container needs additional memory holding the maintenance information needed by the container. Hence, whenever a certain type shall be stored in an intrusive container [*you have to change the definition of that type] appropriately. Although this task is easy with [*Boost.Intrusive], touching the definition of a type is sometimes a crucial issue. * In intrusive containers you don't store a copy of an object, [*but they rather the original object is linked with other objects in the container]. Objects don't need copy-constructors or assignment operators to be stored in intrusive containers. But you have to take care of possible side effects, whenever you change the contents of an object (this is especially important for associative containers). * The user [*has to manage the lifetime of inserted objects] independently from the containers. * Again you have to be [*careful]: in contrast to STL containers [*it's easy to render an iterator invalid] without touching the intrusive container directly, because the object can be disposed before is erased from the container. * [*Boost.Intrusive] containers are [*non-copyable and non-assignable]. Since intrusive containers don't have allocation capabilities, these operations have no sense. However, swapping can be used to implement move-capabilities. To ease the implementation of copy constructors and assignment operators of classes storing [*Boost.Intrusive] containers, [*Boost.Intrusive] offers special cloning functions. See [link boost_intrusive.clone_from Cloning [*Boost.Intrusive] containers] section for more information. * Analyzing thread-safety of a program that uses containers is harder with intrusive containers, becuase the container might be modified indirectly without an explicitly call to a container member. [table Summay of intrusive containers advantages and disadvantages [[Issue] [Intrusive] [Non-intrusive]] [[Memory management] [External] [Internal through allocator]] [[Insertion/Erasure time] [Faster] [Slower]] [[Memory locality] [Better] [Worse]] [[Can hold non-copyable and non-movable objects by value] [Yes] [No]] [[Exception guarantees] [Better] [Worse]] [[Computation of iterator from value] [Constant] [Non-constant]] [[Insertion/erasure predictability] [High] [Low]] [[Memory use] [Minimal] [More than minimal]] [[Insert objects by value retaining polymorphic behavior] [Yes] [No (slicing)]] [[User must modify the definition of the values to insert] [Yes] [No]] [[Containers are copyable] [No] [Yes]] [[Inserted object's lifetime managed by] [User (more complex)] [Container (less complex)]] [[Container invariants can be broken without using the container] [Easier] [Harder (only with containers of pointers)]] [[Thread-safety analysis] [Harder] [Easier]] ] For a performance comparison between Intrusive and Non-intrusive containers see [link boost_intrusive.performance Performance] section. [endsect] [endsect] [section:usage How to use Boost.Intrusive] If you plan to use a class in an intrusive container, you have to make some decisions influencing the class definition itself. Each class that will be used in an intrusive container needs some appropriate data members storing the information needed by the container. We will take a simple intrusive container, like an intrusive list ([classref boost::intrusive::list boost::intrusive::list]) for the following examples, but all [*Boost.Intrusive] containers are very similar. To compile the example using [classref boost::intrusive::list boost::intrusive::list], just include: [c++] #include Every class to be inserted in an intrusive container, needs to contain a hook that will offer the necessary data and resources to be insertable in the container. With [*Boost.Intrusive] you just choose the hook to be a public base class or a public member of the class to be inserted. [section:usage_base_hook Using base hooks] For [classref boost::intrusive::list list], you can publicly derive from [classref boost::intrusive::list_base_hook list_base_hook]. This class takes three template arguments: [c++] template < class Tag = tag , linking_policy Policy = safe_link , class VoidPointer = void *> class list_base_hook; * The first template argument serves as a tag, so you can derive from more than one [classref boost::intrusive::list_base_hook list_base_hook] and hence put an object in multiple intrusive lists at the same time. An incomplete type can serve as a tag. * The second template argument controls the linking policy. [*Boost.Intrusive] currently supports 3 policies: `normal_link`, `safe_link`, `auto_unlink`. More about these in the sections [link boost_intrusive.safe_hook Safe hooks] and [link boost_intrusive.auto_unlink_hooks Auto-unlink hooks] * The third template argument is the pointer type to be used internally in the hook. The default value is `void *`, which means that raw pointers will be used in the hook. More about this in the section titled [link boost_intrusive.using_smart_pointers Using smart pointers with Boost.Intrusive containers] Example: [c++] #include using namespace boost::intrusive; class Foo : public list_base_hook<> { /**/ }; Once we derive our class from `list_base_hook<>` we have to obtain the `ValueTraits` information to configure the intrusive list. `ValueTraits` tell the container the needed information to insert the object in the container (if the hook is a base or member object, whether is an auto-unlink hook... To obtain the needed value traits, just use the `value_traits` subtype [classref boost::intrusive::list_base_hook list_base_hook] defines passing the type of the user class as an argument: [c++] typedef list_base_hook<>::value_traits FooValueTraits; After that, we can define the intrusive list. The intrusive list has the following template parameters: [c++] template < class ValueTraits , bool ConstantTimeSize = true , class SizeType = std::size_t> class list; * The first template argument is the value traits class. Contains information about the value to be inserted: the type, the type of hook, the type of the pointers to be used, whether the safe mode is being used... * The second boolean template argument specifies if a constant time `size()` function is demanded. This will tell the intrusive container to insert an additional member in the intrusive container that offers this information. * The third template argument specifies the type that will hold the size of the container. This type will be the type returned by `list.size()` and the type stored in the intrusive container if `ConstantTimeSize` is requested. The user normally will not need to change this type, but some containers can have a `size_type` that might be different from std::size_t (for example, STL-like containers, use the `size_type` defined by their allocator). [*Boost.Intrusive] can be used to implement such containers specifying the `SizeType` type. Example of a constant-time size intrusive list that will store Foo objects: [c++] typedef list FooList; Now we can just use the container: [c++] //An object to be inserted in the list Foo foo_object; FooList list; list.push_back(object); assert(&list.front() == &foo_object); [endsect] [section:usage_member_hook Using member hooks] Sometimes an 'is-a' relationship between list hooks and the list value types is not desirable. In this case, using a member hook as a data member instead of 'disturbing' the hierarchy might be the right way: you can add a public data member `list_member_hook<...>` to your class. This class takes two template parameters: [c++] template < linking_policy Policy = safe_link , class VoidPointer = void *> class list_member_hook; Example: [c++] #include class Foo { public: list_member_hook<> m_hook_; //... }; To obtain the `ValueTraits` information to configure the list, use the internal templatized `value_traits` type and pass the class to be inserted and a pointer to the member hook as template parameters. [c++] //Obtain ValueTraits to configure the list typedef list_member_hook<>::value_traits FooValueTraits; //This list will use the member hook typedef list FooList; Now we can just use the container: [c++] //An object to be inserted in the list Foo foo_object; FooList list; list.push_back(object); assert(&list.front() == &foo_object); [endsect] [section:usage_both_hooks Using both hooks] You can insert the same object in several intrusive containers at the same time, just using one hook for each containers. This is a full example using base and member hooks: [import ../example/doc_how_to_use.cpp] [doc_how_to_use_code] [endsect] [section:usage_lifetime Object lifetime] Even if the interface of [classref boost::intrusive::list list] is similar to `std::list`, its usage is a bit different: You always have to keep in mind that you directly store objects in intrusive containers, not copies. The lifetime of a stored object is not bound to or managed by the container: * When the container gets disposed before the object, the object is not disposed, so you have to be careful to avoid resource leaks. * When the object is disposed before the container, your program is likely to crash, because the container contains a pointer to an non-existing object. [endsect] [endsect] [section:usage_when When to use?] Intrusive containers can be used for highly optimized algorithms, where speed is a crucial issue and... * additional memory management should be avoided. * the programmer needs to efficiently track the construction and destruction of objects. * exception safety, especially the no-throw guarantee, is needed. * the computation of an iterator to an element from a pointer or reference to that element should be a constant time operation. * it's important to achieve a well-known worst-time system response. * localization of data (e.g. for cache hit optimization) leads to measureable effects. The last point is important if you have a lot of containers over a set of elements. E.g. if you have a vector of objects (say, `std::vector`) and you also have a list storing a subset of those objects (`std::list`), then operating on an Object from the list iterator (`std::list::iterator`) needs two steps: * Access from the iterator (usually on the stack) to the list node storing a pointer to `Object`. * Access from the pointer to `Object` to the Object stored in the vector. While the objects themselves are tightly packed in the memory of the vector (vector's memory is guaranteed to be contiguous), and form something like a data block, list nodes can stay dispersed in the heap memory. Hence depending on your system you can get a lot of cache misses. The same doesn't hold for an intrusive list. Indeed, dereferencing an an iterator from an intrusive list is performed in the same two steps as described above. But the list node is already embedded in the Object, so the memory is directly tracked from the iterator to the Object. It's also possible to use intrusive containers when the objects to be stored can have different or unknown size. This allows storing base and derived objects in the same container as shown in the following example: [import ../example/doc_window.cpp] [doc_window_code] Due to certain properties of intrusive containers they are often more difficult to use than their STL-counterparts. That's why you should avoid them in public interfaces of libraries. Classes to be stored in intrusive containers must change their implementation to store the hook and this is not always posible or desirable. [endsect] [section:concepts_summary Concept summary] Here is a small summary of the basic concepts that will be used in the following chapters: [variablelist Brief Concepts Summary [[Node Algorithms][A class containing typedefs and static functions that define basic operations that can be applied to a groups of nodes. It's independent from the node definition, and it's configured taking a NodeTraits template parameter that describes the node.]] [[Node Traits][A class that stores basic information and operations to insert a node in a group of nodes.]] [[Hook][A class that a user must add as a base class or as a member to make the user class compatible with intrusive containers.]] [[Intrusive Container][A class that stores user classes that have the needed hooks. It takes a ValueTraits template parameter as configuration information.]] [[Pseudo-Intrusive Container][Similar to an intrusive container but a pseudo-intrusive container needs additional memory (e.g. an auxiliary array) to work.]] [[Value Traits][A class containing typedefs and operations to obtain the node to be used by Node Algorithms from the user class and the inverse.]] ] [endsect] [section:presenting_containers Presenting Boost.Intrusive containers] [*Boost.Intrusive] offers a wide range of intrusive containers: * [*slist]: An intrusive singly linked list. The size overhead is very small for user classes (usually the size of one pointer) but many operations have linear time complexity, so the user must be careful if he wants to avoid performance problems. * [*list]: A `std::list` like intrusive linked list. The size overhead is quite small for user classes (usually the size of two pointers). Many operations have constant time complexity. * [*set/multiset]: A `std::set/std::multiset` like intrusive associative containers. The size overhead is moderate for user classes (usually the size of three pointers). Many operations have logarithmic time complexity. [*Boost.Intrusive] also offers pseudo-intrusive containers: * [*unordered_set/unordered_multiset]: A `std::tr1::unordered_set/std::tr1::unordered_multiset` like intrusive unordered associative containers. The size overhead is moderate for user classes (an average of two pointers per element). Many operations have an amortized constant time complexity. Each of these intrusive containers can be configured with constant or linear time size: * [*Linear time size]: The intrusive container doesn't hold a size member that it's updated with every insertion/erasure. This implies that the `size()` function has not constant time complexity. On the other hand, the container is smaller, and some operations, like `splice()` taking a range of iterators in linked lists have constant time complexity instead of linear complexity. * [*Constant time size]: The intrusive container holds a size member that it's updated with every insertion/erasure. This implies that the `size()` function has constant time complexity. On the other hand, increases the size of the container, and some operations, like `splice()` taking a range of iterators, have linear time complexity in linked lists. To make user classes compatible with these intrusive containers [*Boost.Intrusive] offers two types of hooks for each container type: * [*Base hook]: The hook is stored as a public base class of the user class. * [*Member hook]: The hook is stored as a public member of the user class. Apart from that, [*Boost.Intrusive] offers additional features: * [*Safe mode hooks]: Hook constructor initializes the internal data to a well-known safe state and intrusive containers check that state before inserting a value in the container. When erasing an element from the container, the container puts the hook in the safe state again. This allows a safer use mode and it can be used to detect programming errors. It implies an slight performance overhead in some operations and can convert some constant time operations in linear time operations. * [*Auto-unlink hooks]: The hook destructor removes the object from the container automatically and the user can safely unlink the object from the container without having any reference to the container. * [*Non-raw pointers]: If the user wants to use smart pointers instead of raw pointers, [*Boost.Intrusive] hooks can be configured to use any type of pointers. This configuration information is also transmitted to the containers, so all the internal pointers used by intrusive containers configured with these hooks will be smart pointers. As an example, [*Boost.Interprocess] defines an smart pointer compatible with shared memory, called `offset_ptr`. [*Boost.Intrusive] can be configured to use this smart pointer to allow shared memory intrusive containers. [endsect] [section:safe_hook Safe hooks] [section:features Features of the safe mode] [*Boost.Intrusive] hooks can be configured to operate in safe-link mode. The safe mode is activated by default: [c++] template class list_base_hook; Thanks to the safe-mode the user can detect without any external reference, if the object is actually inserted in any 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 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 the default state and if it's inserted in a container, the hook is not in the default state. [endsect] [section:configuring 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 for all the libraries, so the user might want to redefine safe-mode assertions without modifying `BOOST_ASSERT`. This can be achieved redefining the following macros: * `BOOST_INTRUSIVE_SAFE_MODE_CONTAINER_INSERTION_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_MODE_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, it will be defaulted to `BOOST_ASSERT`. [endsect] [endsect] [section:auto_unlink_hooks Auto-unlink hooks] [section:auto_unlink_hooks_what What's an auto-unlink hook?] [*Boost.Intrusive] offers additional hooks with unique features: * When the destructor of the hook is called, the hook checks if the node is inserted in a container. If so, the hook removes the node from the container. * The hook has a member function called `unlink()` that can be used to unlink the node from the container at any moment, without having any reference to the container, if the user want to do so. These hooks have exactly the same size overhead as their analogue non auto-unlinking hooks, but they have a restriction: they can only be used with [link boost_intrusive.presenting_containers non-constant time containers]. There is a reason for this: * Auto-unlink hooks don't store any reference to the container where they are inserted. * Only containers with non constant-time `size()` allow removing an object from the container without using any reference to the container. This auto-unlink feature is useful in certain applications but it must be used [*very carefuly]: * If several threads are using the same container the destructor of the auto-unlink hook will be called without any thread synchronization so removing the object is thread-unsafe. * Container contents change silently without modifying the container directly. This can lead to surprising effects. These auto-unlink hooks have also safe-mode properties: * Hooks' constructors put the hook in a well-known default state. * Every time an object is being inserted in the intrusive container, the container checks if the hook is 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. [endsect] [section:auto_unlink_hooks_example Auto-unlink hook example] Let's see an example of an auto-unlink hook: [import ../example/doc_auto_unlink.cpp] [doc_auto_unlink_code] [endsect] [section:auto_unlink_and_constant_time Auto-unlink hooks and containers with constant-time `size()`] As explained, [*Boost.Intrusive] auto-unlink hooks are incompatible with containers that have constant-time `size()`, so if you try to define such container with an auto-unlink hook's value_traits, you will get an static assertion: [c++] #include struct MyTag; class MyClass : public boost::intrusive::list_base_hook {/**/}; boost::intrusive::list , true> bad_list; int main() { bad_list list; return 0; } leads to an error similar to: [pre error : use of undefined type 'boost::STATIC_ASSERTION_FAILURE' ] Pointing to code like this: [c++] //Constant-time size is incompatible with auto-unlink hooks! BOOST_STATIC_ASSERT(!(ConstantTimeSize && ((int)ValueTraits::linking_policy == (int)auto_unlink))); This way, there is no way to compile a program if you try to use auto-unlink hooks in constant-time size containers. [endsect] [endsect] [section:slist Intrusive singly linked list: slist] [classref boost::intrusive::slist slist] is the simplest intrusive container of [*Boost.Intrusive]: a singly linked list. The memory overhead that imposes is 1 pointer per node. The size of an empty, non constant-time size [classref boost::intrusive::slist slist], is the size of 1 pointer. This lightweight memory overhead comes with its drawbacks, though: many operations have linear time complexity, even some that usually are constant time, like [classref boost::intrusive::slist::swap swap]. [classref boost::intrusive::slist slist] only provides forward iterators. For most cases, a doubly linked list is preferrable because it offers more constant-time functions with a slightly bigger overhead. However, for some applications like constructing more elaborated containers, singly linked lists are essential because of their low size overhead. [section:slist_hooks slist hooks] Like the rest of [*Boost.Intrusive] containers, [classref boost::intrusive::slist slist] has two hook types: [c++] template class slist_base_hook; * [classref boost::intrusive::slist_base_hook slist_base_hook]: the user class derives publicly from [classref boost::intrusive::slist_base_hook slist_base_hook] to make it [classref boost::intrusive::slist slist]-compatible. [c++] template class slist_member_hook; * [classref boost::intrusive::slist_member_hook slist_member_hook]: the user class contains a public [classref boost::intrusive::slist_member_hook slist_member_hook] to make it [classref boost::intrusive::slist slist]-compatible. [endsect] [section:slist_container slist container] [classref boost::intrusive::slist slist] receives 3 template parameters: [c++] template class slist; * The first template is the value traits class. Contains information about the value to be inserted: the type, the type of hook, the type of the pointers to be used, whether the safe mode is being used... * The second boolean template argument specifies if a constant time `size()` function is demanded. This will tell the intrusive container to insert an additional member in the intrusive container that offers this information. * The third template argument specifies the type that will hold the size of the container. This type will be the type returned by `list.size()` and the type stored in the intrusive container if `ConstantTimeSize` is requested. [endsect] [section:slist_example Example] Now let's see an small example using both hooks: [import ../example/doc_slist.cpp] [doc_slist_code] [endsect] [endsect] [section:list Intrusive doubly linked list: list] [classref boost::intrusive::list list] is a doubly linked list. The memory overhead that imposes is 2 pointers per node. An empty, non constant-time size [classref boost::intrusive::list list] has also the size of 2 pointers. [classref boost::intrusive::list list] has many more constant-time operations than [classref boost::intrusive::slist slist] and provides bidirectional iterator. It's recommendable to use use [classref boost::intrusive::list list] instead of [classref boost::intrusive::slist slist] if the size overhead is acceptable: [section:list_hooks list hooks] Like the rest of [*Boost.Intrusive] containers, [classref boost::intrusive::list list] has two hook types: [c++] template class list_base_hook; * [classref boost::intrusive::list_base_hook list_base_hook]: the user class derives publicly from [classref boost::intrusive::list_base_hook list_base_hook] to make it [classref boost::intrusive::list list]-compatible. [c++] template class list_member_hook; * [classref boost::intrusive::list_member_hook list_member_hook]: the user class contains a public [classref boost::intrusive::list_member_hook list_member_hook] to make it [classref boost::intrusive::list list]-compatible. [endsect] [section:list_container list container] [classref boost::intrusive::list list] receives 3 template parameters: [c++] template class list; * The first template is the value traits class. Contains information about the value to be inserted: the type, the type of hook, the type of the pointers to be used, whether the safe mode is being used... * The second boolean template argument specifies if a constant time `size()` function is demanded. This will tell the intrusive container to insert an additional member in the intrusive container that offers this information. * The third template argument specifies the type that will hold the size of the container. This type will be the type returned by `list.size()` and the type stored in the intrusive container if `ConstantTimeSize` is requested. [endsect] [section:list_example Example] Now let's see an small example using both hooks: [import ../example/doc_list.cpp] [doc_list_code] [endsect] [endsect] [section:set_multiset Intrusive associative containers: set, multiset] [*Boost.Intrusive] also offers associative containers that can be very useful when creating more complex associative containers, like containers maintaining one or more indices with different sorting semantics. The memory overhead of these containers is usually 3 pointers and an integer. If pointers have 2 byte alignment (which is usually true in most systems), [*Boost.Intrusive] optimizes this overhead to 3 pointers. An empty, non constant-time size [classref boost::intrusive::set set] or [classref boost::intrusive::multiset multiset] has also the size of 3 pointers and an integer (3 pointers when optimized). [classref boost::intrusive::set set] and [classref boost::intrusive::multiset multiset] have logarithmic complexity in many operations like searches, insertions, erasures, etc... [classref boost::intrusive::set set] and [classref boost::intrusive::multiset multiset] are the intrusive equivalents of standard `std::set` and `std::multiset` containers. [section:set_multiset_hooks set and multiset hooks] [classref boost::intrusive::set set] and [classref boost::intrusive::multiset multiset] share the same hooks. This is an advantage, because the same user type can be inserted first in a [classref boost::intrusive::multiset multiset] and after that in [classref boost::intrusive::set set] without changing the definition of the user class. [c++] template class set_base_hook; * [classref boost::intrusive::set_base_hook set_base_hook]: the user class derives publicly from [classref boost::intrusive::set_base_hook set_base_hook] to make it [classref boost::intrusive::set set]/[classref boost::intrusive::multiset multiset]-compatible. [c++] template class set_member_hook; * [classref boost::intrusive::set_member_hook set_member_hook]: the user class contains a public [classref boost::intrusive::set_member_hook set_member_hook] to make it [classref boost::intrusive::set set]/[classref boost::intrusive::multiset multiset]-compatible. [endsect] [section:set_multiset_containers set and multiset containers] [classref boost::intrusive::set set] and [classref boost::intrusive::multiset multiset] receive 4 template parameters: [c++] template < class ValueTraits , class Compare = std::less , bool ConstantTimeSize = true , class SizeType = std::size_t > class set; template < class ValueTraits , class Compare = std::less , bool ConstantTimeSize = true , class SizeType = std::size_t > class multiset; * The first template is the value traits class. Contains information about the value to be inserted: the type, the type of hook, the type of the pointers to be used, whether the safe mode is being used... * The second template is the ordering function of the associative container. By default, the ordering function is `std::less<...>` of the user value. * The third boolean template argument specifies if a constant time `size()` function is demanded. This will tell the intrusive container to insert an additional member in the intrusive container that offers this information. * The fourth template argument specifies the type that will hold the size of the container. This type will be the type returned by `list.size()` and the type stored in the intrusive container if `ConstantTimeSize` is requested. [endsect] [section:set_multiset_example Example] Now let's see an small example using both hooks and both containers: [import ../example/doc_set.cpp] [doc_set_code] [endsect] [endsect] [section:unordered_set_unordered_multiset Pseudo-Intrusive unordered associative containers: unordered_set, unordered_multiset] [*Boost.Intrusive] also offers hashed containers that can be very useful develop fast-lookup intrusive containers. These containers ([classref boost::intrusive::unordered_set unordered_set] and [classref boost::intrusive::unordered_multiset unordered_multiset]) are pseudo-intrusive containers: they need additional memory apart from the hook that the value_type of the container must add as a base or member. This additional memory must be passed in the constructor of the container. Unlike C++ TR1 unordered associative containers (which are also hashed containers), the contents of these pseudo-intrusive containers are not rehashed to maintain a load factor: that would require memory management and intrusive containers don't implement any memory management at all. However, the user can request an explicit rehashing passing a new bucket array. This also offers an additional guarantee over TR1 unordered associative containers: [*iterators are not invalidated when inserting an element] in the container. As with TR1 unordered associative containers, rehashing invalidates iterators, changes ordering between elements, and changes which buckets elements appear in, but does not invalidate pointers or references to elements. [*Boost.Intrusive] unordered associative containers need five arguments to be passed in their constructors: A pointer to an array of elements whose type is called `bucket_type`, the length of that array, the hash function to be used with the values and an equality functor for those values: [c++] template< class ValueTraits , class Hash = boost::hash , class Equal = std::equal_to , bool ConstantTimeSize = true , class SizeType = std::size_t > class unordered_set { // ... typedef /*implementation defined*/ bucket_type; typedef /*implementation defined*/ bucket_ptr; typedef /*implementation defined*/ size_type; //Constructor unordered_set ( bucket_ptr buckets , size_type buckets_len , const Hash &hasher = Hash() , const Equal &equal = Equal()) ; // ... }; Each hashed container needs [*its own bucket array]. Two hashed containers [*can't] share the same `bucket_type` elements. The bucket array [*must] be disposed [*after] the container using it is disposed, otherwise, the result is undefined. [section:unordered_set_unordered_multiset_performance unordered_set and unordered_multiset performance notes] The size overhead for a hashed container is moderate: 1 pointer per value plus a bucket array per container. The size of an element of the bucket array is usually one pointer. To obtain a good performance hashed container, the bucket length is usually the same as the number of elements that the container contains, so a well-balanced hashed container (`bucket_count()` is equal to `size()` ) will have an equivalent overhead of two pointers per element. An empty, non constant-time size [classref boost::intrusive::unordered_set unordered_set] or [classref boost::intrusive::unordered_multiset unordered_multiset] has also the size of `bucket_count()` pointers. Insertions, erasures, and searches, have amortized constant-time complexity in hashed containers. However, some worst-case guarantees are linear. See [classref boost::intrusive::unordered_set unordered_set] or [classref boost::intrusive::unordered_multiset unordered_multiset] for complexity guarantees of each operation. [*Be careful with non constant-time size hashed containers]: some operations, like `empty()`, have linear complexity, unlike other [*Boost.Intrusive] containers. [endsect] [section:unordered_set_unordered_multiset_hooks unordered_set and unordered_multiset hooks] [classref boost::intrusive::unordered_set unordered_set] and [classref boost::intrusive::unordered_multiset unordered_multiset] share the same hooks. This is an advantage, because the same user type can be inserted first in a [classref boost::intrusive::unordered_multiset unordered_multiset] and after that in [classref boost::intrusive::unordered_set unordered_set] without changing the definition of the user class. [c++] template class unordered_set_base_hook; * [classref boost::intrusive::unordered_set_base_hook unordered_set_base_hook]: the user class derives publicly from [classref boost::intrusive::unordered_set_base_hook unordered_set_base_hook] to make it [classref boost::intrusive::unordered_set unordered_set]/[classref boost::intrusive::unordered_multiset unordered_multiset]-compatible. [c++] template class unordered_set_member_hook; * [classref boost::intrusive::unordered_set_member_hook unordered_set_member_hook]: the user class contains a public [classref boost::intrusive::unordered_set_member_hook unordered_set_member_hook] to make it [classref boost::intrusive::unordered_set unordered_set]/[classref boost::intrusive::unordered_multiset unordered_multiset]-compatible. [endsect] [section:unordered_set_unordered_multiset_containers unordered_set and unordered_multiset containers] [classref boost::intrusive::unordered_set unordered_set] and [classref boost::intrusive::unordered_multiset unordered_multiset] receive 5 template parameters: [c++] template< class ValueTraits , class Hash = boost::hash , class Equal = std::equal_to , bool ConstantTimeSize = true , class SizeType = std::size_t > class unordered_set; template< class ValueTraits , class Hash = boost::hash , class Equal = std::equal_to , bool ConstantTimeSize = true , class SizeType = std::size_t > class unordered_multiset; * The first template is the value traits class. Contains information about the value to be inserted: the type, the type of hook, the type of the pointers to be used, whether the safe mode is being used... * The second template is the hash function of the associative container. It takes a value_type argument and returns a std::size_t. By default, the hash function is `boost::hash<...>` of the user value. * The third template is the equality function of the associative container. By default, the equality function is `std::equal_to<...>` of the user value. * The fourth boolean template argument specifies if a constant time `size()` function is demanded. This will tell the intrusive container to insert an additional member in the intrusive container that offers this information. [*Be careful with non constant-time size() hashed containers] since they have a linear complexity `empty()` function. * The fifth template argument specifies the type that will hold the size of the container. This type will be the type returned by `list.size()` and the type stored in the intrusive container if `ConstantTimeSize` is requested. [endsect] [section:unordered_set_unordered_multiset_example Example] Now let's see an small example using both hooks and both containers: [import ../example/doc_unordered_set.cpp] [doc_unordered_set_code] [endsect] [endsect] [section:advanced_lookups_insertions Advanced lookup and insertion functions for associative containers] [section:advanced_lookups Advanced lookups] [*Boost.Intrusive] associative containers offer the same interface as STL associative containers. However, STL and TR1 ordered and unordered simple associative containers (`std::set`, `std::multiset`, `std::tr1::unordered_set` and `std::tr1::unordered_multiset`) have some inefficiencies caused by the interface: the user can only operate with `value_type` objects. When using these containers we must use `iterator find(const value_type &value)` to find a value. The same happens in other functions like `equal_range`, `lower_bound`, `upper_bound`... However, sometimes the object to be searched it's quite expensive to construct: [import ../example/doc_assoc_optimized_code.cpp] [doc_assoc_optimized_code_normal_find] `Expensive` is an expensive object to construct. If "key" c-string is quite long `Expensive` has to construct a `std::string` using heap memory. Like `Expensive`, many times the only member taking part in ordering issues is just a small part of the class. For example, with `Expensive`, only the internal `std::string` is needed to compare the object. In both containers, if we call `get_from_set/get_from_unordered_set` in a loop, we might get a performance penalty, because we are forced to create a whole `Expensive` object to be able to find an equivalent one. Sometimes this interface limitation is severe, because we [*might not have enough information to construct the object] but we might [*have enough information to find the object]. In this case, a name it's enough to search `Expensive` in the container but constructing an `Expensive` might require more information that the user might not have. To solve this, [classref boost::intrusive::set set]/[classref boost::intrusive::multiset multiset] offer alternative functions, which take any type comparable with the value and a functor that should be compatible with the ordering function of the associative container. [classref boost::intrusive::unordered_set unordered_set]/[classref boost::intrusive::unordered_multiset unordered_multiset] offers functions that take any key type and compatible hash and equality functions. Now, let's see the optimized search function: [doc_assoc_optimized_code_optimized_find] This new arbitrary key overload is also available for other functions taking values as arguments: * equal_range * lower_bound * upper_bound * count * find * erase Check [classref boost::intrusive::set], [classref boost::intrusive::multiset], [classref boost::intrusive::unordered_set], [classref boost::intrusive::unordered_multiset] references to know more about those functions. [endsect] [section:advanced_insertions Advanced insertions] A similar issue happens with insertions in simple ordered and unordered associative containers with unique keys (`std::set` and `std::tr1::unordered_set`). In these containers, if a value is already present, the value to be inserted is discarded. With expensive values, if the value is already present, we can suffer efficiency problems. [classref boost::intrusive::set set] and [classref boost::intrusive::unordered_set unordered_set] have insertion functions to check efficiently, without constructing the value, if a value is present or not and if it's not present, a function to insert it immediately without any further lookup. For example, using the same `Expensive` class, this function can be inefficient: [doc_assoc_optimized_code_normal_insert] If the object is already present, we are constructing an `Expensive` that will be discarded, and this is a waste of resources. Instead of that, let's use `insert_check` and `insert_commit` functions: [doc_assoc_optimized_code_optimized_insert] `insert_check` is similar to a normal `insert` but: * `insert_check` can be used with arbitrary keys * if the insertion is possible (there is no equivalent value) collects all the needed information in an `insert_commit_data` structure, so that `insert_commit`: * [*does not execute] further comparisons * can be executed with [*constant-time complexity] * has [*no-throw guarantee]. These functions must be used with care, since no other insertion or erasure must be executed between an `insert_check` and an `insert_commit` pair. Otherwise, the behaviour is undefined. `insert_check` and `insert_commit` will come handy for developers programming efficient non-intrusive associative containers. See [classref boost::intrusive::set set] and [classref boost::intrusive::unordered_set unordered_set] reference for more information about `insert_check` and `insert_commit`. With multiple ordered and unordered associative containers ([classref boost::intrusive::multiset multiset] and [classref boost::intrusive::unordered_multiset unordered_multiset]) there's no need for these advanced insertion functions, since insertions are always succesful. [endsect] For more information about advanced lookup and insertion functions see [classref boost::intrusive::set set], [classref boost::intrusive::multiset multiset], [classref boost::intrusive::unordered_set unordered_set] and [classref boost::intrusive::unordered_multiset unordered_multiset] references. [endsect] [section:erasing_and_disposing Erasing and disposing values from Boost.Intrusive containers] One of the most tedious tasks when using intrusive containers is the management of the erased elements. When using STL containers, the container itself unlinks and destroys the contained elements, but with intrusive containers, the user must explicitly destroy the object after erasing an element from the container. This makes STL-like functions erasing multiple objects unhelpful: the user can't destroy every erased element. For example, let's take the function `remove_if` from [classref boost::intrusive::list list]: [c++] template void remove_if(Pred pred); How can the user destroy the elements (say, using `operator delete`) that will be erased according to the predicate? [*Boost.Intrusive] containers offer additional functions that take a function object that will be called after the element has been erased from the container. For example, [classref boost::intrusive::list list] offers: [c++] template void remove_and_dispose_if(Pred pred, Disposer disposer) With this function the user can efficiently remove and destroy elements if the disposer function destroys an object: `remove_and_dispose_if` will call "disposer" function object for every removed element. [classref boost::intrusive::list list] offers more functions taking a disposer function object as argument, like `erase_and_dispose`, `clear_and_dispose`, `remove_and_dispose`... Note that the disposing function does not need to just destroy the object. It can implement any other operation like inserting the remove object in another container. Let's see an small example: [import ../example/doc_erasing_and_disposing.cpp] [doc_erasing_and_disposing] All [*Boost.Intrusive] containers offer these "erase + dispose" additional members for all functions that erase an element from the container. [endsect] [section:clone_from Cloning [*Boost.Intrusive] containers] As previously mentioned, [*Boost.Intrusive] containers are [*non-copyable and non-assignable], because intrusive containers don't allocate memory at all. To implement a copy-constructor or assignment operator, the user must clone one by one all the elements of the container and insert them in another intrusive container. However, cloning by hand is usually more inefficient than a member cloning function and an specialized cloning function can offer more guarantees than the manual cloning (better exception safety guarantees, for example). To ease the implementation of copy constructors and assignment operators of classes containing [*Boost.Intrusive] containers, all [*Boost.Intrusive] containers offer an special cloning function called `clone_from`. Apart from the container to be cloned, `clone_from` takes two function objects as arguments. For example, the `clone_from` member function of [classref boost::intrusive::list list]: [c++] template void clone_from(const list &src, Cloner cloner, Disposer disposer); This function will make `*this` a clone of `src`. Let's explain the arguments: * The first parameter is the list to be cloned. * The second parameter is a function object that will clone `value_type` objects and return a pointer to the clone. It must implement the following function: `pointer operator()(const value_type &)`. * The second parameter is a function object that will dispose `value_type` objects. It's used first to empty the container before cloning and to dispose the elements if an exception is thrown. The cloning function works as follows: * First clears and disposes all the elements from *this using the disposer function object. * After that starts cloning all the elements of the source container using the cloner function object. * If any operation in the cloning function (for example, the cloner function object) throws, all the constructed elements are disposed using the disposer function object. Here's an example of `clone_from`: [import ../example/doc_clone_from.cpp] [doc_clone_from] [endsect] [section:using_smart_pointers Using smart pointers with Boost.Intrusive containers] [*Boost.Intrusive] hooks can be configured to use other pointers than raw pointers. When a [*Boost.Intrusive] hook is configured with an smart pointer as an argument, this pointer configuration is passed to the containers. For example, if the following hook is configured with an smart pointer (for example, an offset pointer from [*Boost.Interprocess]): [import ../example/doc_offset_ptr.cpp] [doc_offset_ptr_0] Any intrusive list constructed using this hook will be ready for shared memory, because the intrusive list will also use offset pointers internally. For example, we can create an intrusive list in shared memory combining [*Boost.Interprocess] and [*Boost.Intrusive]: [doc_offset_ptr_1] [section:smart_pointers_requirements Requirements for smart pointers compatible with Boost.Intrusive] Not every smart pointer is compatible with [*Boost.Intrusive], the smart pointer must have the following features: * It must support the same operations as a raw pointer, except casting. * It must be convertible to a raw pointer and constructible from a raw pointer. * It must have the same ownership semantics as a raw pointer. This means that resource management smart pointers (like `boost::shared_ptr`) can't be used. The conversion from the smart pointer to a raw pointer must be implemented following Boost smart pointer `get_pointer()` function. This function will be found using ADL. For example, for `boost::interprocess::offset_ptr` `get_pointer` is defined as follows: [c++] template T * get_pointer(boost::interprocess::offset_ptr const & p) { return p.get(); } [endsect] [endsect] [section:obtaining_iterators_from_values Obtaining iterators from values] [*Boost.Intrusive] offers another useful feature that's not present in STL containers: it's possible to obtain an iterator to a value from the value itself. This feature is implemented in [*Boost.Intrusive] containers by a function called `iterator_to`: [c++] iterator iterator_to(reference value); const_iterator iterator_to(const_reference value); For [*Boost.Intrusive] containers that have local iterators, like unordered associative containers, we can also obtain local iterators: [c++] local_iterator local_iterator_to(reference value); const_local_iterator local_iterator_to(const_reference value); For most [*Boost.Intrusive] containers ([classref boost::intrusive::list list], [classref boost::intrusive::slist slist], [classref boost::intrusive::set set], [classref boost::intrusive::multiset multiset]) `iterator_to` is an static function so we don't need a reference to the container to obtain the iterator. For unordered associative containers ([classref boost::intrusive::unordered_set unordered_set], [classref boost::intrusive::multiset multiset]), `iterator_to` is not an static function, so there is need to have a reference to the container. On the other hand, `local_iterator_to` functions are static. Let's see an small function that shows the use of `iterator_to` and `local_iterator_to`: [import ../example/doc_iterator_from_value.cpp] [doc_iterator_from_value] [endsect] [section:concepts Concepts explained] This section will expand the explanation of previously presented basic concepts before explaining the customization options of [*Boost.Intrusive]. * [*Node Algorithms]: A set of static functions that implement basic operations on a group of nodes: initialize a node, link a node to a group of nodes, unlink a node from another group of nodes... For example, a circular singly linked list is a group of nodes, where each node has a pointer to the next node. [*Node Algorithms] just require a [*NodeTraits] template parameter and they can work with any [*NodeTraits] class that fulfills the needed interface. As an example, here is a class that implements algorithms to manage a group of nodes forming a circular singly linked list: [c++] template struct my_slist_algorithms { typedef typename NodeTraits::node_ptr node_ptr; typedef typename NodeTraits::const_node_ptr const_node_ptr; //Get the previous node of "this_node" static node_ptr get_prev_node(node_ptr this_node) { node_ptr p = this_node; while (this_node != NodeTraits::get_next(p)) p = NodeTraits::get_next(p); return p; } // number of elements in the group of nodes containing "this_node" static std::size_t count(const_node_ptr this_node) { std::size_t result = 0; const_node_ptr p = this_node; do{ p = NodeTraits::get_next(p); ++result; } while (p != this_node); return result; } // More operations // ... }; * [*Node Traits]: A class that encapsulates the basic information and operations on a node that forms a group of nodes: the type of the node, a function to obtain the pointer to the next node... [*Node Traits] are the configuration information [*Node Algorithms] need. Each type of [*Node Algorithms] expects an interface that compatible [*Node Traits] must implement. As an example, this is the definition of a [*Node Traits] class that is compatible with the previously presented `my_slist_algorithms`: [c++] struct my_slist_node_traits { //The type of the node struct node { node *next_; }; typedef node * node_ptr; typedef const node * const_node_ptr; //A function to obtain a pointer to the next node static node_ptr get_next(const_node_ptr n) { return n->next_; } //A function to set the pointer to the next node static void set_next(node_ptr n, node_ptr next) { n->next_ = next; } }; * [*Hook]: A class that the user must add as a base class or as a member to his own class to make that class insertable in an intrusive container. Usually the hook contains a node object, that will be used to form the group of nodes: For example, the following class is a [*Hook] that the user can add as a base class, to make the user class compatible with a singly linked list container: [c++] class my_slist_base_hook //This hook contains a node, that will be used //to link the user object in the group of nodes : private my_slist_node_traits::node { typedef my_slist_node_traits::node_ptr node_ptr; typedef my_slist_node_traits::const_node_ptr const_node_ptr; //Converts the generic node to the hook static my_slist_base_hook *to_hook_ptr(node_ptr p) { return static_cast(p); } //Returns the generic node stored by this hook node_ptr to_node_ptr() { return static_cast(this); } // More operations // ... }; //To make MyClass compatible with an intrusive singly linked list //derive our class from the hook. class MyClass : public my_slist_base_hook { void set(int value); int get() const; private: int value_; }; * [*Intrusive Container]: A container that offers an STL-like interface to store user objects. An intrusive container can be templatized to store different value types that use different hooks. An intrusive container is also more elaborated than a group of nodes: it can store the number of elements to achieve constant-time size information, it can offer debugging facilities... For example, an [classref boost::intrusive::slist slist] container (intrusive singly linked list) should be able to hold `MyClass` objects that might have decided to store the hook as a base class or as a member. Internally, the container will use [*Node Algorithms] to implement its operations, and an intrusive container is configured using a template parameter called [*ValueTraits]. [*ValueTraits] will contain the information to convert user classes in nodes compatible with [*Node Algorithms]. For example, this a possible [classref boost::intrusive::slist slist] implementation: [c++] template class slist { public: typedef typename ValueTraits::value_type value_type; //More typedefs and functions // ... //Insert the value as the first element of the list void push_front (reference value) { node_ptr to_insert(ValueTraits::to_node_ptr(value)); circular_list_algorithms::link_after(to_insert, get_root_node()); } // More operations // ... }; * [*Pseudo-Intrusive Container]: A pseudo-intrusive container is similar to an intrusive container, but apart from the values to be inserted in the container, it needs additional memory (for example, auxiliary arrays or indexes). * [*Value Traits]: As we can see, to make our classes intrusive-friendly we add a simple hook as a member or base class. The hook contains a generic node that will be inserted in a group of nodes. [*Node Algorithms] just work with nodes and don't know anything about user classes. On the other hand, an intrusive container needs to know how to obtain a node from a user class, and also the inverse operation. So we can define [*ValueTraits] as the glue between user classes and nodes required by [*Node Algorithms]. Let's see a possible implementation of a value traits class that glues MyClass and the node stored in the hook: [c++] struct my_slist_derivation_value_traits { public: typedef slist_node_traits node_traits; typedef MyClass value_type; typedef node_traits::node_ptr node_ptr; typedef value_type* pointer; //... //Converts user's value to a generic node static node_ptr to_node_ptr(reference value) { return static_cast(value).to_node_ptr(); } //Converts a generic node into user's value static value_type *to_value_ptr(node_traits::node *n) { static_cast(slist_base_hook::to_hook_ptr(n)); } // More operations // ... }; [endsect] [section:node_algorithms Node algorithms with custom NodeTraits] As explained in the [link boost_intrusive.concepts Concepts] section, [*Boost.Intrusive] containers are implemented using node algorithms that work on generic nodes. Sometimes, the use of intrusive containers is expensive for some environments and the programmer might want to avoid all the template instantiations related to [*Boost.Intrusive] containers. However, the user can still benefit from [*Boost.Intrusive] using the node algorithms, because some of those algorithms, like red-black tree algorithms, are not trivial to write. All node algorithm classes are templatized by a `NodeTraits` class. This class encapsulates the needed internal type declarations and operations to make a node compatible with node algorithms. Each type of node algorithms has its own requirements: [section:circular_slist_algorithms Intrusive singly linked list algorithms] These algorithms are static members of the [classref boost::intrusive::circular_slist_algorithms circular_slist_algorithms] class: [c++] template struct circular_slist_algorithms; An empty list is formed by a node whose pointer to the next node points to itself. [classref boost::intrusive::circular_slist_algorithms circular_slist_algorithms] is configured with a NodeTraits class, which encapsulates the information about the node to be manipulated. NodeTraits must support the following interface: [*Typedefs]: * `node`: The type of the node that forms the circular list * `node_ptr`: The type of a pointer to a node (usually node*) * `const_node_ptr`: The type of a pointer to a const node (usually const node*) [*Static functions]: * `static node_ptr get_next(const_node_ptr n);`: Returns a pointer to the next node stored in "n". * `static void set_next(node_ptr n, node_ptr next);`: Sets the pointer to the next node stored in "n" to "next". Once we have a node traits configuration we can use [*Boost.Intrusive] algorithms with our nodes: [import ../example/doc_slist_algorithms.cpp] [doc_slist_algorithms_code] For a complete list of functions see [classref boost::intrusive::circular_slist_algorithms circular_slist_algorithms reference]. [endsect] [section:circular_list_algorithms Intrusive doubly linked list algorithms] These algorithms are static members of the [classref boost::intrusive::circular_list_algorithms circular_list_algorithms] class: [c++] template struct circular_list_algorithms; An empty list is formed by a node whose pointer to the next node points to itself. [classref boost::intrusive::circular_list_algorithms circular_list_algorithms] is configured with a NodeTraits class, which encapsulates the information about the node to be manipulated. NodeTraits must support the following interface: [*Typedefs]: * `node`: The type of the node that forms the circular list * `node_ptr`: The type of a pointer to a node (usually node*) * `const_node_ptr`: The type of a pointer to a const node (usually const node*) [*Static functions]: * `static node_ptr get_next(const_node_ptr n);`: Returns a pointer to the next node stored in "n". * `static void set_next(node_ptr n, node_ptr next);`: Sets the pointer to the next node stored in "n" to "next". * `static node_ptr get_previous(const_node_ptr n);`: Returns a pointer to the previous node stored in "n". * `static void set_previous(node_ptr n, node_ptr prev);`: Sets the pointer to the previous node stored in "n" to "prev". Once we have a node traits configuration we can use [*Boost.Intrusive] algorithms with our nodes: [import ../example/doc_list_algorithms.cpp] [doc_list_algorithms_code] For a complete list of functions see [classref boost::intrusive::circular_list_algorithms circular_list_algorithms reference]. [endsect] [section:rbtree_algorithms Intrusive red-black tree algorithms] These algorithms are static members of the [classref boost::intrusive::rbtree_algorithms rbtree_algorithms] class: [c++] template struct rbtree_algorithms; An empty tree is formed by a node whose pointer to the parent node is null, the pointers to the left and right nodes to itself and whose color is red. [classref boost::intrusive::rbtree_algorithms rbtree_algorithms] is configured with a NodeTraits class, which encapsulates the information about the node to be manipulated. NodeTraits must support the following interface: [*Typedefs]: * `node`: The type of the node that forms the circular rbtree * `node_ptr`: The type of a pointer to a node (usually node*) * `const_node_ptr`: The type of a pointer to a const node (usually const node*) * `color`: The type that can store the color of a node [*Static functions]: * `static node_ptr get_parent(const_node_ptr n);`: Returns a pointer to the parent node stored in "n". * `static void set_parent(node_ptr n, node_ptr p);`: Sets the pointer to the parent node stored in "n" to "p". * `static node_ptr get_left(const_node_ptr n);`: Returns a pointer to the left node stored in "n". * `static void set_left(node_ptr n, node_ptr l);`: Sets the pointer to the left node stored in "n" to "l". * `static node_ptr get_right(const_node_ptr n);`: Returns a pointer to the right node stored in "n". * `static void set_right(node_ptr n, node_ptr r);`: Sets the pointer to the right node stored in "n" to "r". * `static color get_color(const_node_ptr n);`: Returns the color stored in "n". * `static void set_color(node_ptr n, color c);`: Sets the color stored in "n" to "c". * `static color black();`: Returns a value representing the black color. * `static color red();`: Returns a value representing the red color. Once we have a node traits configuration we can use [*Boost.Intrusive] algorithms with our nodes: [import ../example/doc_rbtree_algorithms.cpp] [doc_rbtree_algorithms_code] For a complete rbtree of functions see [classref boost::intrusive::rbtree_algorithms rbtree_algorithms reference]. [endsect] [endsect] [section:value_traits Containers with custom ValueTraits] As explained in the [link boost_intrusive.concepts Concepts] section, [*Boost.Intrusive] containers are templatized using a `ValueTraits` parameter. This parameter contains all the information to glue the `value_type` of the containers and the node to be used in node algorithms, since these types can be different. Apart from this, `ValueTraits` also store information about the link policy of the values to be inserted. Instead of using [*Boost.Intrusive] predefined hooks a user might want to develop customized containers, for example, using nodes that are optimized for an specific application or that are compatible with a a legacy ABI. A user might want to have only two additional pointers in his class and insert the class in a doubly linked list sometimes and in a singly linked list in other situations. You can't achieve this using [*Boost.Intrusive] predefined hooks. [section:value_traits_interface ValueTraits interface] `ValueTraits` have the following interface: [c++] #include #include struct my_value_traits { typedef implementation_defined node_traits; typedef implementation_defined value_type; typedef node_traits::node_ptr node_ptr; typedef node_traits::const_node_ptr const_node_ptr; typedef boost::pointer_to_other::type pointer; typedef boost::pointer_to_other::type const_pointer; enum { linking_policy = some_linking_policy }; static node_ptr to_node_ptr (value_type &value); static const_node_ptr to_node_ptr (const value_type &value); static pointer to_value_ptr (node_ptr n); static const_pointer to_value_ptr (const_node_ptr n); }; Let's explain each type and function: * ['node_traits]: The node configuration that it's needed by node algorithms. These node traits and algorithms are described in the previous chapter: [link boost_intrusive.node_algorithms Nodes Algorithms]. * If my_value_traits is meant to be used with [classref boost::intrusive::slist slist], `node_traits` should follow the interface needed by [classref boost::intrusive::circular_slist_algorithms circular_slist_algorithms]. * If my_value_traits is meant to be used with [classref boost::intrusive::list list], `node_traits` should follow the interface needed by [classref boost::intrusive::circular_list_algorithms circular_list_algorithms]. * If my_value_traits is meant to be used with [classref boost::intrusive::set set]/[classref boost::intrusive::multiset multiset], `node_traits` should follow the interface needed by [classref boost::intrusive::rbtree_algorithms rbtree_algorithms]. * If my_value_traits is meant to be used with [classref boost::intrusive::unordered_set unordered_set]/ [classref boost::intrusive::unordered_multiset unordered_multiset], `node_traits` should follow the interface needed by [classref boost::intrusive::circular_slist_algorithms circular_slist_algorithms]. * ['node_ptr]: A typedef for `node_traits::node_ptr`. * ['const_node_ptr]: A typedef for `node_traits::const_node_ptr`. * ['value_type]: The type that the user wants to insert in the container. This type can be the same as `node_traits::node` but it can be different (for example, `node_traits::node` can be a member type of `value_type`). If `value_type` and `node_traits::node` are the same type, the `to_node_ptr` and `to_value_ptr` functions are trivial. * ['pointer]: The type of a pointer to a `value_type`. It must be the same pointer type as `node_ptr`: If `node_ptr` is `node *` `pointer` must be `value_type*`. If `node_ptr` is `smart_ptr`, `pointer` must be `smart_ptr`. This can be generically achieved using `boost::pointer_to_other` utility from [*Boost SmartPointers] defined in ``. * ['const_pointer]: The type of a pointer to a `const value_type`. It must be the same pointer type as `node_ptr`: If `node_ptr` is `node *` `const_pointer` must be `const value_type*`. If `node_ptr` is `smart_ptr`, `const_pointer` must be `smart_ptr` This can be generically achieved using `boost::pointer_to_other` utility from [*Boost SmartPointers] defined in ``. * ['linking_policy]: Indicates that `value_traits` needs some additional work or checks from the container. The types are enumerations defined in the `value_traits_type.hpp` header. These are the possible types: * `normal_link`: If this linking policy is specified in a `ValueTraits` class as the linking_policy, containers configured with such `ValueTraits` won't set the hooks of the erased values to a default state. Containers also won't check that the hooks of the new values are default initialized. normal_link, * `safe_link`: If this linking policy is specified in a `ValueTraits` class as the linking_policy, containers configured with such `ValueTraits` will set the hooks of the erased values to a default state. Containers also will check that the hooks of the new values are default initialized. * `auto_unlink`: Same as "safe_link" but containers with constant-time size features won't be compatible with `ValueTraits` configured with this policy. Containers also know that the a value can be silently erased from the container without using any function provided by the containers. * ['static node_ptr to_node_ptr (value_type &value)] and ['static const_node_ptr to_node_ptr (const value_type &value)]: These function take a reference to a value_type and return a pointer to the node to be used with node algorithms. * ['static pointer to_value_ptr (node_ptr n)] and ['static const_pointer to_value_ptr (const_node_ptr n)]: These function take a pointer to a node and return a pointer to the value that contains the node. [endsect] [section:value_traits_example Custom ValueTraits example] Let's define our own `value_traits` class to be able to use [*Boost.Intrusive] containers with an old C structure whose definition can't be changed. That legacy type has two pointers that can be used to build singly and doubly linked lists: in singly linked lists we only need a pointer, whereas in doubly linked lists, we need two pointers. Since we only have two pointers, we can't insert the object in a singly and doubly linked list at the same time. This is the definition of the old node: [import ../example/doc_value_traits.cpp] [doc_value_traits_code_legacy] Now we have to define a NodeTraits class that will implement the functions/typedefs that will make the legacy node compatible with [*Boost.Intrusive] algorithms. After that, we'll define a ValueTraits class that will configure [*Boost.Intrusive] containers: [doc_value_traits_value_traits] Now we can just define the containers that will store the legacy abi objects and write a little test: [doc_value_traits_test] As seen, several key elements of [*Boost.Intrusive] can be reused with custom user types, if the user does not want to use provided [*Boost.Intrusive] facilities. [endsect] [section:reusing_node_algorithms Reusing node algorithms for different values] In the previous example, `legacy_node_traits::node` type and `legacy_value_traits::value_type` are the same type, but this is not necessary. It's possible to have several `ValueTraits` defining the same `node_traits` type (and thus, the same `node_traits::node`). This reduces the number of node algorithm instantiations, but now `ValueTraits::to_node_ptr` and `ValueTraits::to_value_ptr` functions need to offer conversions between both types. Let's see an small example: First, we'll define the node to be used in the algorithms. For a linked list, we just need a node that stores two pointers: [import ../example/doc_advanced_value_traits.cpp] [doc_advanced_value_traits_code] Now we'll define two different types that will be inserted in intrusive lists and we'll define a templatized `ValueTraits` that will work for both types: [doc_advanced_value_traits_value_traits] Now define two containers. Both containers will instantiate the same list algorithms (`circular_list_algorithms`), due to the fact that the value traits used to define the containers provide the same `node_traits` type: [doc_advanced_value_traits_containers] All [*Boost.Intrusive] containers using predefined hooks use this technique to minimize code size: all the possible [classref boost::intrusive::list list] containers created with predefined hooks that define the same `VoidPointer` type share the same list algorithms. [endsect] [endsect] [section:thread_safety Thread safety guarantees] Intrusive containers have similar same thread-safety guarantees than STL containers. * Serveral threads can have read or write access to different instances is safe as long as inserted objects are different. * Concurrent read-only access to the same container is safe. Some Intrusive hooks (auto-unlink hooks, for example) modify containers without having a reference to them: this is considered a write access to the container. Other functions, like checking if an objects is already inserted in a containers using the `is_linked()` member of safe hooks is a read-access to the container without having a reference to them, so no other thread should have write access (direct or indirect) to that container. Since the same object can be inserted in several containers at the same time using different hooks, the thread safety of [*Boost.Intrusive] is related to the containers and also the object whose lifetime is manually managed by the user. As we can see, the analysis of the thread-safety of a program using [*Boost.Intrusive] is harder than with non-intrusive containers. To analyze the thread-safety, take in care the following points: * Auto-unlink hook's destructor and `unlink()` functions modify the container indirectly. * Safe mode and auto-unlink hook's `is_linked()` function is a read access to the container. * Inserting an object in several containers that will be modified by different threads has no thread-safety guarantee, although in most platforms it will be thread-safe without locking. [endsect] [section:design_notes Design Notes] When designing [*Boost.Intrusive] the following guidelines have been taken into account: [section: Boost.Intrusive in performance sensitive environments] [*Boost.Intrusive] should be a valuable tool in performance sensitive environments, and following this guideline, [*Boost.Intrusive] has been designed to offer well known complexity guarantees. Apart from that, some options, like optional constant-time, have been designed to offer faster complexity guarantees in some functions, like `slist::splice`. The advanced lookup and insertion functions for associative containers, taking an arbitrary key type and predicates, were designed to avoid unnecessary object constructions. [endsect] [section: Boost.Intrusive in space constrained environments] [*Boost.Intrusive] should be useful in space constrained environments, and following this guideline [*Boost.Intrusive] separates node algorithms and intrusive containers to avoid instantiating node algorithms for each user type. For example, a single class of red-black algorithms will be instantiated to implement all set and multiset containers using raw pointers. This way, [*Boost.Intrusive] wants to avoid any code size overhead associated with templates. Apart from that, [*Boost.Intrusive] implements some size improvements: for example, red-black trees embed the color bit in the parent pointer lower bit, if nodes are two-byte aligned. The possibility to avoid constant-time size operations can save some size on containers, and this extra size optimization is noticeable when the container is empty or contains few values. [endsect] [section: Boost.Intrusive as basic building block] [*Boost.Intrusive] should be a basic building block to build more complex containers and this guideline has motivated many design decisions. For example, the possibility to have more than one hook per user type opens the possibility to implement multi-index containers on top of [*Boost.Intrusive]. [*Boost.Intrusive] containers implement advanced functions taking function objects as arguments (`clone_from`, `erase_and_dispose`, `insert_check`...). These functions come handy when implementing non-intrusive containers (for example, STL-like containers) on top of intrusive containers. [endsect] [section: Extending Boost.Intrusive] [*Boost.Intrusive] offers a wide range of containers but also allows the construction of custom containers reusing [*Boost.Intrusive] elements. The programer might want to use node algorithms directly or build special hooks that take advantage of its application environment. For example, the programmer can use can customize parts of [*Boost.Intrusive] to manage old data structures whose definition can't be changed. [endsect] [endsect] [section:performance Performance] [*Boost.Intrusive] containers offer speed improvements comparing to non-intrusive containers, basically because: * We can minimize memory allocation/deallocation calls. * We obtain better memory locality. This section will show some performance tests comparing some operations on `boost::intrusive::list` and `std::list`: * Insertions using `push_back` and container destruction will show the overhead associated with memory allocation/deallocation. * `reverse` member function will show the advantages of the compact memory representation that can be achieved with intrusive containers. * `sort` and `write access` tests will show the advantage of intrusive containers minimizing the memory accesses when comparing them with containers of pointers. Given an object of type `T`, [classref boost::intrusive::list boost::intrusive::list<...>] can replace `std::list` to avoid memory allocation overhead, or it can replace `std::list` when the user wants to obtain containers with polymorphic values or wants to share values between several containers. Because of this versatility, the performance tests will be executed for 6 different list types: * 3 intrusive lists holding a class named `itest_class`, each one with a different linking policy (`normal_link`, `safe_link`, `auto_unlink`). The `itest_class` objects will be tightly packed in a `std::vector` object. * `std::list`, where `test_class` is exactly the same as `itest_class`, but without the intrusive hook. * `std::list`. The list will contain pointers to `test_class` objects tightly packed in a `std::vector` object. We'll call this configuration ['compact pointer list] * `std::list`. The list will contain pointers to `test_class` objects owned by a `std::list` object. We'll call this configuration ['disperse pointer list]. Both `test_class` and `itest_class` are templatized classes that can be configured with a boolean to increase the size of the object. This way, the tests can be executed with small and big objects. Here is the first part of the testing code, which shows the definitions of `test_class` and `itest_class` classes, and some other utilities: [import ../perf/perf_list.cpp] [perf_list_value_type] As we can see, `test_class` is a very simple class holding an `int`. `itest_class` is just a class that has a base hook ([classref boost::intrusive::list_base_hook list_base_hook]) and also derives from `test_class`. `func_ptr_adaptor` is just a functor adaptor to convert function objects taking `test_list` objects to funtion objects taking pointers to them. You can find the full test code code in the [@../../perf/perf_list.cpp perf_list.cpp] source file. [section:performance_results_push_back Back insertions and destruction] The first test will measure the benefits we can obtain with intrusive containers avoiding memory allocations and deallocations . All the objects to be inserted in intrusive containers are allocated in a single allocation call, whereas `std::list` will need to allocate memory for every and deallocate it for every erasure (or container destruction). Let's compare the code to be executed for each container type for different insertion tests: [perf_list_push_back_intrusive] For intrusive containers, all the values are created in a vector and after that inserted in the intrusive list. [perf_list_push_back_stdlist] For a standard list, elements are pushed back using push_back(). [perf_list_push_back_stdptrlist] For a standard compact pointer list, elements are created in a vector and pushed back in the pointer list using push_back(). [perf_list_push_back_disperse_stdptrlist] For a ['disperse pointer list], elements are created in a list and pushed back in the pointer list using push_back(). These are the times in microseconds for each case, and the normalized time: [table Back insertion + destruction times for Visual C++ 7.1 / Windows XP [[Container] [Time in us/iteration (small object / big object)] [Normalized time (small object / big object)]] [[`normal_link` intrusive list] [5000 / 22500] [1 / 1]] [[`safe_link` intrusive list] [7812 / 32187] [1.56 / 1.43]] [[`auto_unlink` intrusive list] [10156 / 41562] [2.03 / 1.84]] [[Standard list] [76875 / 97500] [5.37 / 4.33]] [[Standard compact pointer list] [76406 / 86718] [15.28 / 3.85]] [[Standard disperse pointer list] [146562 / 175625] [29.31 / 7.80]] ] [table Back insertion + destruction times for GCC 4.1.1 / MinGW over Windows XP [[Container] [Time in us/iteration (small object / big object)] [Normalized time (small object / big object)]] [[`normal_link` intrusive list] [4375 / 22187] [1 / 1]] [[`safe_link` intrusive list] [7812 / 32812] [1.78 / 1.47]] [[`auto_unlink` intrusive list] [10468 / 42031] [2.39 / 1.89]] [[Standard list] [81250 / 98125] [18.57 / 4.42]] [[Standard compact pointer list] [83750 / 94218] [19.14 / 4.24]] [[Standard disperse pointer list] [155625 / 175625] [35.57 / 7.91]] ] [table Back insertion + destruction times for GCC 4.1.2 / Linux Kernel 2.6.18 (OpenSuse 10.2) [[Container] [Time in us/iteration (small object / big object)] [Normalized time (small object / big object)]] [[`normal_link` intrusive list] [4792 / 20495] [1 / 1]] [[`safe_link` intrusive list] [7709 / 30803] [1.60 / 1.5]] [[`auto_unlink` intrusive list] [10180 / 41183] [2.12 / 2.0]] [[Standard list] [17031 / 32586] [3.55 / 1.58]] [[Standard compact pointer list] [27221 / 34823] [5.68 / 1.69]] [[Standard disperse pointer list] [102272 / 60056] [21.34 / 2.93]] ] The results are logical: intrusive lists just need one allocation. The destruction time of the `normal_link` intrusive container is trivial (complexity: `O(1)`), whereas `safe_link` and `auto_unlink` intrusive containers need to the hook of erased values' in the default state (complexity: `O(NumElements)`). That's why `normal_link` intrusive list shines in this test. Non-intrusive containers need to make much more allocations and that's why they are lagging behind. The `disperse pointer list` needs to make `NumElements*2` allocations, so the result is not surprising. Linux test shows that standard containers are do very well against intrusive containers with big objects. Nearly the same GCC version in MinGW performs worse, so maybe the a good operating system memory allocator is the reason for this good results. [endsect] [section:performance_results_reversing Reversing] The next test measures the time needed to complete calss to the member function `reverse()`. Values (`test_class` and `itest_class`) and lists are created like explained in the previous section. Note that for pointer lists, `reverse` [*does not need to access `test_class` values stored in another list or vector], since this function just needs to adjust internal pointers, so in theory, all tested lists need to perform the same operations. These are the results: [table Reverse times for Visual C++ 7.1 / Windows XP [[Container] [Time in us/iteration (small object / big object)] [Normalized time (small object / big object) (small object / big object)]] [[`normal_link` intrusive list] [2656 / 10625] [1 / 1.83]] [[`safe_link` intrusive list] [2812 / 10937] [1.05 / 1.89]] [[`auto_unlink` intrusive list] [2710 / 10781] [1.02 / 1.86]] [[Standard list] [5781 / 14531] [2.17 / 2.51]] [[Standard compact pointer list] [5781 / 5781] [2.17 / 1]] [[Standard disperse pointer list] [10781 / 15781] [4.05 / 2.72]] ] [table Reverse times for GCC 4.1.1 / MinGW over Windows XP [[Container] [Time in us/iteration (small object / big object)] [Normalized time (small object / big object)]] [[`normal_link` intrusive list] [2656 / 10781] [1 / 2.22]] [[`safe_link` intrusive list] [2656 / 10781] [1 / 2.22]] [[`auto_unlink` intrusive list] [2812 / 10781] [1.02 / 2.22]] [[Standard list] [4843 / 12500] [1.82 / 2.58]] [[Standard compact pointer list] [4843 / 4843] [1.82 / 1]] [[Standard disperse pointer list] [9218 / 12968] [3.47 / 2.67]] ] [table Reverse times for GCC 4.1.2 / Linux Kernel 2.6.18 (OpenSuse 10.2) [[Container] [Time in us/iteration (small object / big object)] [Normalized time (small object / big object)]] [[`normal_link` intrusive list] [2742 / 10847] [1 / 3.41]] [[`safe_link` intrusive list] [2742 / 10847] [1 / 3.41]] [[`auto_unlink` intrusive list] [2742 / 11027] [1 / 3.47]] [[Standard list] [3184 / 10942] [1.16 / 3.44]] [[Standard compact pointer list] [3207 / 3176] [1.16 / 1]] [[Standard disperse pointer list] [5814 / 13381] [2.12 / 4.21]] ] For small objects the results show that the compact storage of values in intrusive containers improve locality and reversing is faster than with standard containers, whose values might be dispersed in memory because each value is independently allocated. Note that the dispersed pointer list (a list of pointers to values allocated in another list) suffers more because nodes of the pointer list might be more dispersed, since allocations from both lists are interleaved in the code: [c++] //Object list (holding `test_class`) stdlist objects; //Pointer list (holding `test_class` pointers) stdptrlist l; for(int i = 0; i < NumElements; ++i){ //Allocation from the object list objects.push_back(stdlist::value_type(i)); //Allocation from the pointer list l.push_back(&objects.back()); } For big values the compact pointer list wins because when reversing does need access to the values stored in another container. Since all the allocations for nodes of this pointer list are likely to be near (since there is no other allocation in the process until the pointer list is created) locality is better than with intrusive containers. The dispersed pointer list, like with small values, has poor locality. [endsect] [section:performance_results_sorting Sorting] The next test measures the time needed to complete calls the member function `sort(Pred pred)`. Values (`test_class` and `itest_class`) and lists are created like explained in the first section. The values will be sorted in ascending and descenting order each iteration. For example, if ['l] is a list: [c++] for(int i = 0; i < NumIter; ++i){ if(!(i % 2)) l.sort(std::greater()); else l.sort(std::less()); } For a pointer list, the function object will be adapted using `func_ptr_adaptor`: [c++] for(int i = 0; i < NumIter; ++i){ if(!(i % 2)) l.sort(func_ptr_adaptor >()); else l.sort(func_ptr_adaptor >()); } Note that for pointer lists, `sort` will take a function object that [*will access `test_class` values stored in another list or vector], so pointer lists will suffer an extra indirection: they will need to access the `test_class` values stored in another container to compare to elements. These are the results: [table Sort times for Visual C++ 7.1 / Windows XP [[Container] [Time in us/iteration (small object / big object)] [Normalized time (small object / big object)]] [[`normal_link` intrusive list] [16093 / 38906] [1 / 1]] [[`safe_link` intrusive list] [16093 / 39062] [1 / 1]] [[`auto_unlink` intrusive list] [16093 / 38906] [1 / 1]] [[Standard list] [32343 / 56406] [2.0 / 1.44]] [[Standard compact pointer list] [33593 / 46093] [2.08 / 1.18]] [[Standard disperse pointer list] [46875 / 68593] [2.91 / 1.76]] ] [table Sort times for GCC 4.1.1 / MinGW over Windows XP [[Container] [Time in us/iteration (small object / big object)] [Normalized time (small object / big object)]] [[`normal_link` intrusive list] [15000 / 39218] [1 / 1]] [[`safe_link` intrusive list] [15156 / 39531] [1.01 / 1.01]] [[`auto_unlink` intrusive list] [15156 / 39531] [1.01 / 1.01]] [[Standard list] [34218 / 56875] [2.28 / 1.45]] [[Standard compact pointer list] [35468 / 49218] [2.36 / 1.25]] [[Standard disperse pointer list] [47656 / 70156] [3.17 / 1.78]] ] [table Sort times for GCC 4.1.2 / Linux Kernel 2.6.18 (OpenSuse 10.2) [[Container] [Time in us/iteration (small object / big object)] [Normalized time (small object / big object)]] [[`normal_link` intrusive list] [18003 / 40795] [1 / 1]] [[`safe_link` intrusive list] [18003 / 41017] [1 / 1]] [[`auto_unlink` intrusive list] [18230 / 40941] [1.01 / 1]] [[Standard list] [26273 / 49643] [1.45 / 1.21]] [[Standard compact pointer list] [28540 / 43172] [1.58 / 1.05]] [[Standard disperse pointer list] [35077 / 57638] [1.94 / 1.41]] ] The results show that intrusive containers are faster than standard containers. We can see that the pointer list holding pointers to values stored in a vector is quite fast, so the extra indirection that needs to access the value is minimized because all the values are tightly stored, improving cache. The disperse list, on the other hand, is slower because the indirection to access to values stored in the object list is more expensive than the access to values stored in a vector. [endsect] [section:performance_results_write_access Write access] The next test measures the time needed to iterate all the elements of a list, and increment the value of the internal `i_` member: [c++] stdlist::iterator it(l.begin()), end(l.end()); for(; it != end; ++it) ++(it->i_); Values (`test_class` and `itest_class`) and lists are created like explained in the first section. Note that for pointer lists, the iteration will suffer an extra indirection: they will need to access the `test_class` values stored in another container: [c++] stdptrlist::iterator it(l.begin()), end(l.end()); for(; it != end; ++it) ++((*it)->i_); These are the results: [table Write access times for Visual C++ 7.1 / Windows XP [[Container] [Time in us/iteration (small object / big object)] [Normalized time (small object / big object)]] [[`normal_link` intrusive list] [2031 / 8125] [1 / 1]] [[`safe_link` intrusive list] [2031 / 8281] [1 / 1.01]] [[`auto_unlink` intrusive list] [2031 / 8281] [1 / 1.01]] [[Standard list] [4218 / 10000] [2.07 / 1.23]] [[Standard compact pointer list] [4062 / 8437] [2.0 / 1.03]] [[Standard disperse pointer list] [8593 / 13125] [4.23 / 1.61]] ] [table Write access times for GCC 4.1.1 / MinGW over Windows XP [[Container] [Time in us/iteration (small object / big object)] [Normalized time (small object / big object)]] [[`normal_link` intrusive list] [2343 / 8281] [1 / 1]] [[`safe_link` intrusive list] [2500 / 8281] [1.06 / 1]] [[`auto_unlink` intrusive list] [2500 / 8281] [1.06 / 1]] [[Standard list] [4218 / 10781] [1.8 / 1.3]] [[Standard compact pointer list] [3906 / 8281] [1.66 / 1]] [[Standard disperse pointer list] [8281 / 13750] [3.53 / 1.66]] ] [table Write access times for GCC 4.1.2 / Linux Kernel 2.6.18 (OpenSuse 10.2) [[Container] [Time in us/iteration (small object / big object)] [Normalized time (small object / big object)]] [[`normal_link` intrusive list] [2286 / 8468] [1 / 1.1]] [[`safe_link` intrusive list] [2381 / 8412] [1.04 / 1.09]] [[`auto_unlink` intrusive list] [2301 / 8437] [1.01 / 1.1]] [[Standard list] [3044 / 9061] [1.33 / 1.18]] [[Standard compact pointer list] [2755 / 7660] [1.20 / 1]] [[Standard disperse pointer list] [6118 / 12453] [2.67 / 1.62]] ] Like with the read access test, the results show that intrusive containers outperform all other containers if the values are tightly packed in a vector. The disperse list is again the slowest one. [endsect] [section:performance_results_conclusions Conclusions] Intrusive containers can offer performance benefits that can not be achieved with equivalent non-intrusive containers. Memory locality improvements are noticeable when objects to be inserted are small. Minimizing memory allocation/deallocation calls is also an important factor and intrusive containers make this simple if the user allocates all the objects to be inserted in intrusive containers in containers like `std::vector` or `std::deque`. [endsect] [endsect] [section:tested_compilers Tested compilers] [*Boost.Intrusive] has been tested in the following compilers/platforms: * Visual 7.1/WinXP * Visual 8.0/WinXP * GCC 4.1.1/MinGW * GCC 3.4.4/Cygwin * Intel 9.1/WinXP * GCC 4.1.2/Linux * Codewarrior 9.4/WinXP * GCC 3.4.3/Solaris 11 * GCC 4.0/Mac Os 10.4.1 [endsect] [section:acknowledgments Acknowledgments] [*Olaf Krzikalla] would like to thank: * [*Markus Schaaf] for pointing out the possibility and the advantages of the derivation approach. * [*Udo Steinbach] for encouragements to present this work for boost, a lot of fixes and helpful discussions. * [*Jaap Suter] for the initial hint, which eventually leads to the member value_traits. [*Ion Gaztanaga] would like to thank: * [*Olaf Krzikalla] for the permission to continue his great work. * [*Joaquín M. López Muñoz] for his thorough review, help, and ideas. * [*Cory Nelson], [*Daniel James], [*Dave Harris], [*Guillaume Melquiond], [*Henri Bavestrello], [*Hervé Brönnimann], [*Kai Brüning], [*Kevin Sopp] [*Paul Rose], [*Pavel Vozelinek], [*Howard Hinnant], [*Olaf Krzikalla], [*Samuel Debionne], [*Stjepan Rajko], [*Thorsten Ottosen], [*Tobias Schwinger], [*Tom Brinkman] and [*Steven Watanabe] for their comments and reviews in the Boost.Intrusive formal review. [endsect] [xinclude intrusive_doxygen.xml] [section:license_notices License notices] The internal implementation of red-black trees is based on that of SGI STL stl_tree.h file: Copyright (c) 1996,1997 Silicon Graphics Computer Systems, Inc. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Silicon Graphics makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. Copyright (c) 1994 Hewlett-Packard Company Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Hewlett-Packard Company makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. [endsect]