diff --git a/doc/intrusive.qbk b/doc/intrusive.qbk index 90684a7..4f37f12 100644 --- a/doc/intrusive.qbk +++ b/doc/intrusive.qbk @@ -1364,163 +1364,6 @@ the unordered container: [endsect] -[section:splay_set_multiset Intrusive splay tree based associative containers: splay_set, splay_multiset and , splay_tree] - -C++ associative containers are usually based on red-black tree implementations (e.g.: STL, -Boost.Intrusive associative containers). However, there are other interesting data -structures that offer some advantages (and also disadvantages). - -Splay trees are self-adjusting binary search trees used typically in caches, memory -allocators and other applications, because splay trees have a "caching effect": recently -accessed elements have better access times than elements accessed less frequently. -For more information on splay trees see [@http://en.wikipedia.org/wiki/Splay_tree Wikipedia entry]. - -[*Boost.Intrusive] offers 3 containers based on splay trees: -[classref boost::intrusive::splay_set splay_set], -[classref boost::intrusive::splay_multiset splay_multiset] and -[classref boost::intrusive::splaytree splaytree]. The first two are similar to -[classref boost::intrusive::set set] or -[classref boost::intrusive::multiset multiset] and the latter is a generalization -that offers functions both to insert unique and multiple keys. - -The memory overhead of these containers with Boost.Intrusive hooks is usually 3 pointers. -An empty, non constant-time size splay container has also a size of 3 pointers. - -[section:splay_set_multiset_disadvantages Advantages and disadvantages of splay tree based containers] - -Splay tree based intrusive containers have logarithmic complexity in many -operations like searches, insertions, erasures, etc., but if some elements are -more frequently accessed than others, splay trees perform faster searches than equivalent -balanced binary trees (such as red-black trees). - -The caching effect offered by splay trees comes with a cost: the tree must be -rebalanced when an element is searched. This disallows const versions of search -functions like `find()`, `lower_bound()`, `upper_bound()`, `equal_range()`, -`count()`, etc. - -Because of this, splay-tree based associative containers are not drop-in -replacements of [classref boost::intrusive::set set]/ -[classref boost::intrusive::multiset multiset]. - -Apart from this, if element searches are randomized, the tree will be rebalanced -without taking advantage of the cache effect, so splay trees can offer worse -performance than other balanced trees for some search patterns. - -[endsect] - -[section:splay_set_multiset_hooks splay_set, splay_multiset and splaytree hooks] - -[classref boost::intrusive::splay_set splay_set], -[classref boost::intrusive::splay_multiset splay_multiset] and -[classref boost::intrusive::splaytree splaytree] -share the same hooks. - -[c++] - - template - class splay_set_base_hook; - -* [classref boost::intrusive::splay_set_base_hook splay_set_base_hook]: - the user class derives publicly from this class to make - it compatible with splay tree based containers. - -[c++] - - template - class splay_set_member_hook; - -* [classref boost::intrusive::set_member_hook set_member_hook]: - the user class contains a public member of this class to make - it compatible with splay tree based containers. - -[classref boost::intrusive::splay_set_base_hook splay_set_base_hook] and -[classref boost::intrusive::splay_set_member_hook splay_set_member_hook] receive -the same options explained in the section -[link intrusive.usage How to use Boost.Intrusive]: - -* [*`tag`] (for base hooks only): This argument serves as a tag, - so you can derive from more than one base hook. - Default: `tag`. - -* [*`link_mode`]: The linking policy. - Default: `link_mode`. - -* [*`void_pointer`]: The pointer type to be used - internally in the hook and propagated to the container. - Default: `void_pointer`. - -[endsect] - -[section:set_multiset_containers splay_set, splay_multiset and splaytree containers] - -[c++] - - template - class splay_set; - - template - class splay_multiset; - - template - class splaytree; - -These containers receive the same options explained in the section -[link intrusive.usage How to use Boost.Intrusive]: - -* [*`base_hook`] / [*`member_hook`] / - [*`value_traits`]: To specify the hook type or value traits used - to configure the container. (To learn about value traits go to the section - [link intrusive.value_traits Containers with custom ValueTraits].) - -* [*`constant_time_size`]: To activate the constant-time `size()` operation. - Default: `constant_time_size` - -* [*`size_type`]: To specify the type that will be used to store the size - of the container. Default: `size_type` - -And they also can receive an additional option: - -* [*`compare`]: Comparison function for the objects to be inserted - in containers. The comparison functor must induce a strict weak ordering. - Default: `compare< std::less >` - -[endsect] - -[section:splay_set_bst_hook Splay trees with BST hooks] - -Intrusive splay containers can also use plain binary search tree hooks -[classref boost::intrusive::bs_set_base_hook bs_set_base_hook] and -[classref boost::intrusive::bs_set_base_hook bs_set_base_hook]. -These hooks can be used by other intrusive containers like -intrusive scapegoat containers -[classref boost::intrusive::sg_set sg_set] and -[classref boost::intrusive::sg_multiset sg_multiset]. A programmer -might prefer using a binary search tree hook so that the same type -can be inserted in some situations in a splay container but -also inserted in other compatible containers when -the hook is not being used in a splay container. - -[classref boost::intrusive::bs_set_base_hook bs_set_base_hook] and -[classref boost::intrusive::bs_set_base_hook bs_set_member_hook] admit -the same options as [classref boost::intrusive::splay_set_base_hook splay_set_base_hook]. - -[endsect] - -[section:splay_set_multiset_example Example] - -Now let's see a small example using both splay hooks, -binary search tree hooks and -[classref boost::intrusive::splay_set splay_set]/ -[classref boost::intrusive::splay_multiset splay_multiset] -containers: - -[import ../example/doc_splay_set.cpp] -[doc_splay_set_code] - -[endsect] - -[endsect] - [section:avl_set_multiset Intrusive avl tree based associative containers: avl_set, avl_multiset and avltree] Similar to red-black trees, AVL trees are balanced binary trees. @@ -1649,6 +1492,103 @@ containers: [endsect] +[section:splay_set_multiset Intrusive splay tree based associative containers: splay_set, splay_multiset and , splay_tree] + +C++ associative containers are usually based on red-black tree implementations (e.g.: STL, +Boost.Intrusive associative containers). However, there are other interesting data +structures that offer some advantages (and also disadvantages). + +Splay trees are self-adjusting binary search trees used typically in caches, memory +allocators and other applications, because splay trees have a "caching effect": recently +accessed elements have better access times than elements accessed less frequently. +For more information on splay trees see [@http://en.wikipedia.org/wiki/Splay_tree the corresponding Wikipedia entry]. + +[*Boost.Intrusive] offers 3 containers based on splay trees: +[classref boost::intrusive::splay_set splay_set], +[classref boost::intrusive::splay_multiset splay_multiset] and +[classref boost::intrusive::splaytree splaytree]. The first two are similar to +[classref boost::intrusive::set set] or +[classref boost::intrusive::multiset multiset] and the latter is a generalization +that offers functions both to insert unique and multiple keys. + +The memory overhead of these containers with Boost.Intrusive hooks is usually 3 pointers. +An empty, non constant-time size splay container has also a size of 3 pointers. + +[section:splay_set_multiset_disadvantages Advantages and disadvantages of splay tree based containers] + +Splay tree based intrusive containers have logarithmic complexity in many +operations like searches, insertions, erasures, etc., but if some elements are +more frequently accessed than others, splay trees perform faster searches than equivalent +balanced binary trees (such as red-black trees). + +The caching effect offered by splay trees comes with a cost: the tree must be +rebalanced when an element is searched. To maintain const-correctness and thread-safety +guarantees, this caching effect is not updated when const versions of +search functions like `find()`, `lower_bound()`, `upper_bound()`, `equal_range()`, +`count()`... are called. This means that using splay-tree based associative containers as drop-in +replacements of [classref boost::intrusive::set set]/ +[classref boost::intrusive::multiset multiset], specially for const search functions, +might not result in desired performance improvements. + +If element searches are randomized, the tree will be continuously srebalanced +without taking advantage of the cache effect, so splay trees can offer worse +performance than other balanced trees for several search patterns. + +[*Boost.Intrusive] splay associative containers don't use their own hook types but plain Binary search tree hooks. +See [link intrusive.bst_hooks Binary search tree hooks: bs_set_base_hook and bs_set_member_hook] section for more +information about these hooks. + +[endsect] + +[section:set_multiset_containers splay_set, splay_multiset and splaytree containers] + +[c++] + + template + class splay_set; + + template + class splay_multiset; + + template + class splaytree; + +These containers receive the same options explained in the section +[link intrusive.usage How to use Boost.Intrusive]: + +* [*`base_hook`] / [*`member_hook`] / + [*`value_traits`]: To specify the hook type or value traits used + to configure the container. (To learn about value traits go to the section + [link intrusive.value_traits Containers with custom ValueTraits].) + +* [*`constant_time_size`]: To activate the constant-time `size()` operation. + Default: `constant_time_size` + +* [*`size_type`]: To specify the type that will be used to store the size + of the container. Default: `size_type` + +And they also can receive an additional option: + +* [*`compare`]: Comparison function for the objects to be inserted + in containers. The comparison functor must induce a strict weak ordering. + Default: `compare< std::less >` + +[endsect] + +[section:splay_set_multiset_example Example] + +Now let's see a small example using +[classref boost::intrusive::splay_set splay_set]/ +[classref boost::intrusive::splay_multiset splay_multiset] +containers: + +[import ../example/doc_splay_set.cpp] +[doc_splay_set_code] + +[endsect] + +[endsect] + [section:sg_set_multiset Intrusive scapegoat tree based associative containers: sg_set, sg_multiset and sgtree] @@ -1705,50 +1645,9 @@ An empty, [classref boost::intrusive::sg_set sg_set], has also the size of 3 pointers, two integers and two floating point values (equivalent to the size of 7 pointers on most systems). -[section:sg_set_multiset_hooks Using binary search tree hooks: bs_set_base_hook and bs_set_member_hook] - -[classref boost::intrusive::sg_set sg_set], -[classref boost::intrusive::sg_multiset sg_multiset] and -[classref boost::intrusive::sgtree sgtree] don't use their -own hooks but plain binary search tree hooks. This has many advantages -since binary search tree hooks can also be used to insert values in -splay and treap containers. - -[c++] - - template - class bs_set_base_hook; - -* [classref boost::intrusive::bs_set_base_hook bs_set_base_hook]: - the user class derives publicly from this class to make - it compatible with scapegoat tree based containers. - -[c++] - - template - class bs_set_member_hook; - -* [classref boost::intrusive::set_member_hook set_member_hook]: - the user class contains a public member of this class to make - it compatible with scapegoat tree based containers. - -[classref boost::intrusive::bs_set_base_hook bs_set_base_hook] and -[classref boost::intrusive::bs_set_member_hook bs_set_member_hook] receive -the same options explained in the section -[link intrusive.usage How to use Boost.Intrusive]: - -* [*`tag`] (for base hooks only): This argument serves as a tag, - so you can derive from more than one base hook. - Default: `tag`. - -* [*`link_mode`]: The linking policy. - Default: `link_mode`. - -* [*`void_pointer`]: The pointer type to be used - internally in the hook and propagated to the container. - Default: `void_pointer`. - -[endsect] +[*Boost.Intrusive] scapegoat associative containers don't use their own hook types but plain Binary search tree hooks. +See [link intrusive.bst_hooks Binary search tree hooks: bs_set_base_hook and bs_set_member_hook] section for more +information about these hooks. [section:sg_set_multiset_containers sg_set, sg_multiset and sgtree containers] @@ -1791,7 +1690,7 @@ And they also can receive additional options: [section:sg_set_multiset_example Example] -Now let's see a small example using both hooks and +Now let's see a small example using binary search tree hooks and [classref boost::intrusive::sg_set sg_set]/ [classref boost::intrusive::sg_multiset sg_multiset] containers: @@ -1841,50 +1740,9 @@ An empty, [classref boost::intrusive::treap_set treap_set], has also the size of 3 pointers and an integer (supposing empty function objects for key and priority comparison and constant-time size). -[section:treap_set_multiset_hooks Using binary search tree hooks: bs_set_base_hook and bs_set_member_hook] - -[classref boost::intrusive::treap_set treap_set], -[classref boost::intrusive::treap_multiset treap_multiset] and -[classref boost::intrusive::treap treap] don't use their -own hooks but plain binary search tree hooks. This has many advantages -since binary search tree hooks can also be used to insert values in -splay containers and scapegoat trees. - -[c++] - - template - class bs_set_base_hook; - -* [classref boost::intrusive::bs_set_base_hook bs_set_base_hook]: - the user class derives publicly from this class to make - it compatible with scapegoat tree based containers. - -[c++] - - template - class bs_set_member_hook; - -* [classref boost::intrusive::set_member_hook set_member_hook]: - the user class contains a public member of this class to make - it compatible with scapegoat tree based containers. - -[classref boost::intrusive::bs_set_base_hook bs_set_base_hook] and -[classref boost::intrusive::bs_set_member_hook bs_set_member_hook] receive -the same options explained in the section -[link intrusive.usage How to use Boost.Intrusive]: - -* [*`tag`] (for base hooks only): This argument serves as a tag, - so you can derive from more than one base hook. - Default: `tag`. - -* [*`link_mode`]: The linking policy. - Default: `link_mode`. - -* [*`void_pointer`]: The pointer type to be used - internally in the hook and propagated to the container. - Default: `void_pointer`. - -[endsect] +[*Boost.Intrusive] treap associative containers don't use their own hook types but plain Binary search tree hooks. +See [link intrusive.bst_hooks Binary search tree hooks: bs_set_base_hook and bs_set_member_hook] section for more +information about these hooks. [section:treap_set_multiset_containers treap_set, treap_multiset and treap containers] @@ -1967,7 +1825,7 @@ the strongest possible behaviour in these situations. In summary: [section:treap_set_multiset_example Example] -Now let's see a small example using both hooks and +Now let's see a small example using binary search tree hooks and [classref boost::intrusive::treap_set treap_set]/ [classref boost::intrusive::treap_multiset treap_multiset] containers: @@ -1979,6 +1837,48 @@ containers: [endsect] +[section:bst_hooks Binary search tree hooks: bs_set_base_hook and bs_set_member_hook] + +Binary search tree hooks can be used with several tree-like containers that don't +need any additional metadata for rebalancing operations. This has many advantages +since binary search tree hooks can also be used to insert values in +plain binary search tree, splay tree, scapegoat tree, and treap containers. + +[c++] + + template + class bs_set_base_hook; + +* [classref boost::intrusive::bs_set_base_hook bs_set_base_hook]: + the user class derives publicly from this class to make + it compatible with the mentioned tree based containers. + +[c++] + + template + class bs_set_member_hook; + +* [classref boost::intrusive::bs_set_member_hook bs_set_member_hook]: + the user class contains a public member of this class to make + it compatible with the mentioned tree based containers. + +[classref boost::intrusive::bs_set_base_hook bs_set_base_hook] and +[classref boost::intrusive::bs_set_member_hook bs_set_member_hook] receive +the same options explained in the section +[link intrusive.usage How to use Boost.Intrusive]: + +* [*`tag`] (for base hooks only): This argument serves as a tag, + so you can derive from more than one base hook. + Default: `tag`. + +* [*`link_mode`]: The linking policy. + Default: `link_mode`. + +* [*`void_pointer`]: The pointer type to be used + internally in the hook and propagated to the container. + Default: `void_pointer`. + +[endsect] [section:advanced_lookups_insertions Advanced lookup and insertion functions for associative containers]