boost-react-native-bundle

<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Containers with custom ValueTraits</title> <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> <meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> <link rel="up" href="../intrusive.html" title="Chapter 15. Boost.Intrusive"> <link rel="prev" href="node_algorithms.html" title="Node algorithms with custom NodeTraits"> <link rel="next" href="thread_safety.html" title="Thread safety guarantees"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <table cellpadding="2" width="100%"><tr> <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> <td align="center"><a href="../../../index.html">Home</a></td> <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> <td align="center"><a href="../../../more/index.htm">More</a></td> </tr></table> <hr> <div class="spirit-nav"> <a accesskey="p" href="node_algorithms.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../intrusive.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="thread_safety.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="intrusive.value_traits"></a><a class="link" href="value_traits.html" title="Containers with custom ValueTraits">Containers with custom ValueTraits</a> </h2></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="value_traits.html#intrusive.value_traits.value_traits_interface">ValueTraits interface</a></dt> <dt><a href="value_traits.html#intrusive.value_traits.value_traits_example">Custom ValueTraits example</a></dt> <dt><a href="value_traits.html#intrusive.value_traits.reusing_node_algorithms">Reusing node algorithms for different values</a></dt> <dt><a href="value_traits.html#intrusive.value_traits.simplifying_value_traits">Simplifying value traits definition</a></dt> <dt><a href="value_traits.html#intrusive.value_traits.stateful_value_traits">Stateful value traits</a></dt> </dl></div> As explained in the <a class="link" href="concepts.html" title="Concepts explained">Concepts</a> section, Boost.Intrusive containers need a <code class="computeroutput">ValueTraits</code> class to perform transformations between nodes and user values. <code class="computeroutput">ValueTraits</code> can be explicitly configured (using the <code class="computeroutput">value_traits<></code> option) or implicitly configured (using hooks and their <code class="computeroutput">base_hook<></code>/<code class="computeroutput">member_hook<></code> options). <code class="computeroutput">ValueTraits</code> contains all the information to glue the <code class="computeroutput">value_type</code> of the containers and the node to be used in node algorithms, since these types can be different. Apart from this, <code class="computeroutput">ValueTraits</code> also stores 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 a specific application or that are compatible with 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. Now, instead of using <code class="computeroutput">base_hook<...></code> or <code class="computeroutput">member_hook<...></code> options the user will specify the <code class="computeroutput">value_traits<...></code> options. Let's see how we can do this: <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="intrusive.value_traits.value_traits_interface"></a><a class="link" href="value_traits.html#intrusive.value_traits.value_traits_interface" title="ValueTraits interface">ValueTraits interface</a> </h3></div></div></div> <code class="computeroutput">ValueTraits</code> has the following interface: <pre class="programlisting">#include <boost/intrusive/pointer_traits.hpp> #include <boost/intrusive/link_mode.hpp> 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::intrusive::pointer_traits<node_ptr>::rebind_traits <value_type>::type::pointer pointer; typedef boost::intrusive::pointer_traits<node_ptr>::rebind_traits <const value_type>::type::pointer const_pointer; static const link_mode_type link_mode = 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); }; </pre> Let's explain each type and function: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> node_traits: The node configuration that is needed by node algorithms. These node traits and algorithms are described in the previous chapter: <a class="link" href="node_algorithms.html" title="Node algorithms with custom NodeTraits">Node Algorithms</a>. <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> <li class="listitem"> If my_value_traits is meant to be used with <code class="computeroutput"><a class="link" href="../boost/intrusive/slist.html" title="Class template slist">slist</a></code>, <code class="computeroutput">node_traits</code> should follow the interface needed by <code class="computeroutput"><a class="link" href="../boost/intrusive/circular_slist_algorithms.html" title="Class template circular_slist_algorithms">circular_slist_algorithms</a></code>. </li> <li class="listitem"> If my_value_traits is meant to be used with <code class="computeroutput"><a class="link" href="../boost/intrusive/list.html" title="Class template list">list</a></code>, <code class="computeroutput">node_traits</code> should follow the interface needed by <code class="computeroutput"><a class="link" href="../boost/intrusive/circular_list_algorithms.html" title="Class template circular_list_algorithms">circular_list_algorithms</a></code>. </li> <li class="listitem"> If my_value_traits is meant to be used with <code class="computeroutput"><a class="link" href="../boost/intrusive/set.html" title="Class template set">set</a></code>/<code class="computeroutput"><a class="link" href="../boost/intrusive/multiset.html" title="Class template multiset">multiset</a></code>, <code class="computeroutput">node_traits</code> should follow the interface needed by <code class="computeroutput"><a class="link" href="../boost/intrusive/rbtree_algorithms.html" title="Class template rbtree_algorithms">rbtree_algorithms</a></code>. </li> <li class="listitem"> If my_value_traits is meant to be used with <code class="computeroutput"><a class="link" href="../boost/intrusive/unordered_set.html" title="Class template unordered_set">unordered_set</a></code>/ <code class="computeroutput"><a class="link" href="../boost/intrusive/unordered_multiset.html" title="Class template unordered_multiset">unordered_multiset</a></code>, <code class="computeroutput">node_traits</code> should follow the interface needed by <code class="computeroutput"><a class="link" href="../boost/intrusive/circular_slist_algorithms.html" title="Class template circular_slist_algorithms">circular_slist_algorithms</a></code>. </li> </ul></div> </li> <li class="listitem"> node_ptr: A typedef for <code class="computeroutput">node_traits::node_ptr</code>. </li> <li class="listitem"> const_node_ptr: A typedef for <code class="computeroutput">node_traits::const_node_ptr</code>. </li> <li class="listitem"> value_type: The type that the user wants to insert in the container. This type can be the same as <code class="computeroutput">node_traits::node</code> but it can be different (for example, <code class="computeroutput">node_traits::node</code> can be a member type of <code class="computeroutput">value_type</code>). If <code class="computeroutput">value_type</code> and <code class="computeroutput">node_traits::node</code> are the same type, the <code class="computeroutput">to_node_ptr</code> and <code class="computeroutput">to_value_ptr</code> functions are trivial. </li> <li class="listitem"> pointer: The type of a pointer to a <code class="computeroutput">value_type</code>. It must be the same pointer type as <code class="computeroutput">node_ptr</code>: If <code class="computeroutput">node_ptr</code> is <code class="computeroutput">node*</code>, <code class="computeroutput">pointer</code> must be <code class="computeroutput">value_type*</code>. If <code class="computeroutput">node_ptr</code> is <code class="computeroutput">smart_ptr<node_traits::node></code>, <code class="computeroutput">pointer</code> must be <code class="computeroutput">smart_ptr<value_type></code>. This can be generically achieved using <code class="computeroutput">boost::intrusive::pointer_traits</code> (portable implementation of C++11 <code class="computeroutput">std::pointer_traits</code>). </li> <li class="listitem"> const_pointer: The type of a pointer to a <code class="computeroutput">const value_type</code>. It must be the same pointer type as <code class="computeroutput">node_ptr</code>: If <code class="computeroutput">node_ptr</code> is <code class="computeroutput">node*</code>, <code class="computeroutput">const_pointer</code> must be <code class="computeroutput">const value_type*</code>. If <code class="computeroutput">node_ptr</code> is <code class="computeroutput">smart_ptr<node_traits::node></code>, <code class="computeroutput">const_pointer</code> must be <code class="computeroutput">smart_ptr<const value_type></code>. </li> <li class="listitem"> link_mode: Indicates that <code class="computeroutput">value_traits</code> needs some additional work or checks from the container. The types are enumerations defined in the <code class="computeroutput">link_mode.hpp</code> header. These are the possible types: <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> <li class="listitem"> <code class="computeroutput">normal_link</code>: If this linking policy is specified in a <code class="computeroutput">ValueTraits</code> class as the link mode, containers configured with such <code class="computeroutput">ValueTraits</code> 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. </li> <li class="listitem"> <code class="computeroutput">safe_link</code>: If this linking policy is specified as the link mode in a <code class="computeroutput">ValueTraits</code> class, containers configured with this <code class="computeroutput">ValueTraits</code> 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. </li> <li class="listitem"> <code class="computeroutput">auto_unlink</code>: Same as "safe_link" but containers with constant-time size features won't be compatible with <code class="computeroutput">ValueTraits</code> configured with this policy. Containers also know that a value can be silently erased from the container without using any function provided by the containers. </li> </ul></div> </li> <li class="listitem"> static node_ptr to_node_ptr (value_type &value) and static const_node_ptr to_node_ptr (const value_type &value): These functions take a reference to a value_type and return a pointer to the node to be used with node algorithms. </li> <li class="listitem"> static pointer to_value_ptr (node_ptr n) and static const_pointer to_value_ptr (const_node_ptr n): These functions take a pointer to a node and return a pointer to the value that contains the node. </li> </ul></div> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="intrusive.value_traits.value_traits_example"></a><a class="link" href="value_traits.html#intrusive.value_traits.value_traits_example" title="Custom ValueTraits example">Custom ValueTraits example</a> </h3></div></div></div> Let's define our own <code class="computeroutput">value_traits</code> 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 both a singly and a doubly linked list at the same time. This is the definition of the old node: <pre class="programlisting">#include <boost/intrusive/link_mode.hpp> #include <boost/intrusive/list.hpp> #include <boost/intrusive/slist.hpp> #include <vector> //This node is the legacy type we can't modify and we want to insert in //intrusive list and slist containers using only two pointers, since //we know the object will never be at the same time in both lists. struct legacy_value { legacy_value *prev_; legacy_value *next_; int id_; }; </pre> 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: <pre class="programlisting">//Define our own NodeTraits that will configure singly and doubly linked //list algorithms. Note that this node traits is compatible with //circular_slist_algorithms and circular_list_algorithms. namespace bi = boost::intrusive; struct legacy_node_traits { typedef legacy_value node; typedef legacy_value * node_ptr; typedef const legacy_value * const_node_ptr; static node *get_next(const node *n) { return n->next_; } static void set_next(node *n, node *next) { n->next_ = next; } static node *get_previous(const node *n) { return n->prev_; } static void set_previous(node *n, node *prev) { n->prev_ = prev; } }; //This ValueTraits will configure list and slist. In this case, //legacy_node_traits::node is the same as the //legacy_value_traits::value_type so to_node_ptr/to_value_ptr //functions are trivial. struct legacy_value_traits { typedef legacy_node_traits node_traits; typedef node_traits::node_ptr node_ptr; typedef node_traits::const_node_ptr const_node_ptr; typedef legacy_value value_type; typedef legacy_value * pointer; typedef const legacy_value * const_pointer; static const bi::link_mode_type link_mode = bi::normal_link; static node_ptr to_node_ptr (value_type &value) { return node_ptr(&value); } static const_node_ptr to_node_ptr (const value_type &value) { return const_node_ptr(&value); } static pointer to_value_ptr(node_ptr n) { return pointer(n); } static const_pointer to_value_ptr(const_node_ptr n) { return const_pointer(n); } }; </pre> Defining a value traits class that simply defines <code class="computeroutput">value_type</code> as <code class="computeroutput">legacy_node_traits::node</code> is a common approach when defining customized intrusive containers, so Boost.Intrusive offers a templatized <code class="computeroutput"><a class="link" href="../boost/intrusive/trivial_value_traits.html" title="Struct template trivial_value_traits">trivial_value_traits</a></code> class that does exactly what we want: <pre class="programlisting">typedef bi::trivial_value_traits<legacy_node_traits, bi::normal_link> trivial_legacy_value_traits; </pre> Now we can just define the containers that will store the legacy abi objects and write a little test: <pre class="programlisting">//Now define an intrusive list and slist that will store legacy_value objects typedef bi::value_traits<legacy_value_traits> ValueTraitsOption; typedef bi::value_traits<trivial_legacy_value_traits> TrivialValueTraitsOption; typedef bi::list<legacy_value, ValueTraitsOption> LegacyAbiList; typedef bi::slist<legacy_value, ValueTraitsOption> LegacyAbiSlist; typedef bi::list<legacy_value, TrivialValueTraitsOption> TrivialLegacyAbiList; typedef bi::slist<legacy_value, TrivialValueTraitsOption> TrivialLegacyAbiSlist; template<class List> bool test_list() { typedef std::vector<legacy_value> Vect; //Create legacy_value objects, with a different internal number Vect legacy_vector; for(int i = 0; i < 100; ++i){ legacy_value value; value.id_ = i; legacy_vector.push_back(value); } //Create the list with the objects List mylist(legacy_vector.begin(), legacy_vector.end()); //Now test both lists typename List::const_iterator bit(mylist.begin()), bitend(mylist.end()); typename Vect::const_iterator it(legacy_vector.begin()), itend(legacy_vector.end()); //Test the objects inserted in our list for(; it != itend; ++it, ++bit) if(&*bit != &*it) return false; return true; } int main() { return test_list<LegacyAbiList>() && test_list<LegacyAbiSlist>() && test_list<TrivialLegacyAbiList>() && test_list<TrivialLegacyAbiSlist>() ? 0 : 1; } </pre> As seen, several key elements of Boost.Intrusive can be reused with custom user types, if the user does not want to use the provided Boost.Intrusive facilities. </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="intrusive.value_traits.reusing_node_algorithms"></a><a class="link" href="value_traits.html#intrusive.value_traits.reusing_node_algorithms" title="Reusing node algorithms for different values">Reusing node algorithms for different values</a> </h3></div></div></div> In the previous example, <code class="computeroutput">legacy_node_traits::node</code> type and <code class="computeroutput">legacy_value_traits::value_type</code> are the same type, but this is not necessary. It's possible to have several <code class="computeroutput">ValueTraits</code> defining the same <code class="computeroutput">node_traits</code> type (and thus, the same <code class="computeroutput">node_traits::node</code>). This reduces the number of node algorithm instantiations, but now <code class="computeroutput">ValueTraits::to_node_ptr</code> and <code class="computeroutput">ValueTraits::to_value_ptr</code> functions need to offer conversions between both types. Let's see a 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: <pre class="programlisting">#include <boost/intrusive/link_mode.hpp> #include <boost/intrusive/list.hpp> #include <vector> //This is the node that will be used with algorithms. struct simple_node { simple_node *prev_; simple_node *next_; }; </pre> Now we'll define two different types that will be inserted in intrusive lists and a templatized <code class="computeroutput">ValueTraits</code> that will work for both types: <pre class="programlisting">class base_1{}; class base_2{}; struct value_1 : public base_1, public simple_node { int id_; }; struct value_2 : public base_1, public base_2, public simple_node { float id_; }; //Define the node traits. A single node_traits will be enough. struct simple_node_traits { typedef simple_node node; typedef node * node_ptr; typedef const node * const_node_ptr; static <span class="identi