Intrusive treap based associative containers: treap_set, treap

Intrusive treap based associative containers: treap_set, treap_multiset and treap

Using binary search tree hooks: bs_set_base_hook and bs_set_member_hook
treap_set, treap_multiset and treap containers
Exception safety of treap-based intrusive containers
Example

The name treap is a mixture of tree and heap indicating that Treaps exhibit the properties of both binary search trees and heaps. A treap is a binary search tree that orders the nodes by a key but also by a priority attribute. The nodes are ordered so that the keys form a binary search tree and the priorities obey the max heap order property.

If v is a left descendant of u, then key[v] < key[u];
If v is a right descendant of u, then key[v] > key[u];
If v is a child of u, then priority[v] <= priority[u];

If priorities are non-random, the tree will usually be unbalanced; this worse theoretical average-case behavior may be outweighed by better expected-case behavior, as the most important items will be near the root. This means most important objects will be retrieved faster than less important items and for items keys with equal keys most important objects will be found first. These properties are important for some applications.

The priority comparison will be provided just like the key comparison, via a function object that will be stored in the intrusive container. This means that the priority can be stored in the value to be introduced in the treap or computed on flight (via hashing or similar).

Boost.Intrusive offers 3 containers based on treaps: treap_set, treap_multiset and treap. The first two are similar to set or 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 3 pointers.

An empty, treap_set, treap_multiset or treap has also the size of 3 pointers and an integer (supposing empty function objects for key and priority comparison and constant-time size).

Using binary search tree hooks: bs_set_base_hook and bs_set_member_hook

treap_set, treap_multiset and 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.

template <class ...Options>
class 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.

template <class ...Options>
class bs_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.

bs_set_base_hook and bs_set_member_hook receive the same options explained in the section How to use Boost.Intrusive:

tag<class Tag> (for base hooks only): This argument serves as a tag, so you can derive from more than one base hook. Default: tag<default_tag>.
link_mode<link_mode_type LinkMode>: The linking policy. Default: link_mode<safe_link>.
void_pointer<class VoidPointer>: The pointer type to be used internally in the hook and propagated to the container. Default: void_pointer<void*>.

treap_set, treap_multiset and treap containers

template <class T, class ...Options>
class treap_set;

template <class T, class ...Options>
class treap_multiset;

template <class T, class ...Options>
class treap;

These containers receive the same options explained in the section How to use Boost.Intrusive:

base_hook<class Hook> / member_hook<class T, class Hook, Hook T::* PtrToMember> / value_traits<class ValueTraits>: To specify the hook type or value traits used to configure the container. (To learn about value traits go to the section Containers with custom ValueTraits.)
constant_time_size<bool Enabled>: To activate the constant-time size() operation. Default: constant_time_size<true>
size_type<bool Enabled>: To specify the type that will be used to store the size of the container. Default: size_type<std::size_t>

And they also can receive additional options:

compare<class Compare>: Comparison function for the objects to be inserted in containers. The comparison functor must induce a strict weak ordering. Default: compare< std::less<T> >
priority<class PriorityCompare>: Priority Comparison function for the objects to be inserted in containers. The comparison functor must induce a strict weak ordering. Default: priority< priority_compare<T> >

The default priority_compare<T> object function will call an unqualified function priority_order passing two constant T references as arguments and should return true if the first argument has higher priority (it will be searched faster), inducing strict weak ordering. The function will be found using ADL lookup so that the user just needs to define a priority_order function in the same namespace as his class:

struct MyType
{
   friend bool priority_order(const MyType &a, const MyType &b)
   {...}
};

namespace mytype {

struct MyType{ ... };

bool priority_order(const MyType &a, const MyType &b)
{...}

}  //namespace mytype {

Exception safety of treap-based intrusive containers

In general, intrusive containers offer strong safety guarantees, but treap containers must deal with two possibly throwing functors (one for value ordering, another for priority ordering). Moreover, treap erasure operations require rotations based on the priority order function and this issue degrades usual erase(const_iterator) no-throw guarantee. However, intrusive offers the strongest possible behaviour in these situations. In summary:

If the priority order functor does not throw, treap-based containers, offer exactly the same guarantees as other tree-based containers.
If the priority order functor throws, treap-based containers offer strong guarantee.

Example

Now let's see a small example using both hooks and treap_set/ treap_multiset containers:

#include <boost/intrusive/treap_set.hpp>
#include <vector>
#include <algorithm>
#include <cassert>

using namespace boost::intrusive;

class MyClass : public bs_set_base_hook<> //This is a base hook
{
   int int_;
   unsigned int prio_;

   public:
   //This is a member hook
   bs_set_member_hook<> member_hook_;

   MyClass(int i, unsigned int prio)  :  int_(i), prio_(prio)
      {}

   unsigned int get_priority() const
   {  return this->prio_;   }

   //Less and greater operators
   friend bool operator< (const MyClass &a, const MyClass &b)
      {  return a.int_ < b.int_;  }
   friend bool operator> (const MyClass &a, const MyClass &b)
      {  return a.int_ > b.int_;  }
   //Default priority compare
   friend bool priority_order (const MyClass &a, const MyClass &b)
      {  return a.prio_ < b.prio_;  }  //Lower value means higher priority
   //Inverse priority compare
   friend bool priority_inverse_order (const MyClass &a, const MyClass &b)
      {  return a.prio_ > b.prio_;  }  //Higher value means higher priority
};

struct inverse_priority
{
   bool operator()(const MyClass &a, const MyClass &b) const
   {  return priority_inverse_order(a, b); }
};


//Define an treap_set using the base hook that will store values in reverse order
typedef treap_set< MyClass, compare<std::greater<MyClass> > >     BaseSet;

//Define an multiset using the member hook that will store
typedef member_hook<MyClass, bs_set_member_hook<>, &MyClass::member_hook_> MemberOption;
typedef treap_multiset
   < MyClass, MemberOption, priority<inverse_priority> > MemberMultiset;

int main()
{
   typedef std::vector<MyClass>::iterator VectIt;

   //Create several MyClass objects, each one with a different value
   std::vector<MyClass> values;
   for(int i = 0; i < 100; ++i)  values.push_back(MyClass(i, (i % 10)));

   BaseSet baseset;
   MemberMultiset membermultiset;
   
   //Now insert them in the sets
   for(VectIt it(values.begin()), itend(values.end()); it != itend; ++it){
      baseset.insert(*it);
      membermultiset.insert(*it);
   }

   //Now test treap_sets
   {
      BaseSet::reverse_iterator rbit(baseset.rbegin()), rbitend(baseset.rend());
      MemberMultiset::iterator mit(membermultiset.begin()), mitend(membermultiset.end());
      VectIt it(values.begin()), itend(values.end());

      //Test the objects inserted in the base hook treap_set
      for(; it != itend; ++it, ++rbit)
         if(&*rbit != &*it)   return 1;

      //Test the objects inserted in the member hook treap_set
      for(it = values.begin(); it != itend; ++it, ++mit)
         if(&*mit != &*it) return 1;

      //Test priority order
      for(int i = 0; i < 100; ++i){
         if(baseset.top()->get_priority() != static_cast<unsigned int>(i/10))
            return 1;
         if(membermultiset.top()->get_priority() != 9u - static_cast<unsigned int>(i/10))
            return 1;
         baseset.erase(baseset.top());
         membermultiset.erase(membermultiset.top());
      }
   }
   return 0;
}