boost/intrusive/list_hook.hpp

   1 /////////////////////////////////////////////////////////////////////////////
   2 //
   3 // (C) Copyright Olaf Krzikalla 2004-2006.
   4 // (C) Copyright Ion Gaztanaga  2006-2008
   5 //
   6 // Distributed under the Boost Software License, Version 1.0.
   7 //    (See accompanying file LICENSE_1_0.txt or copy at
   8 //          http://www.boost.org/LICENSE_1_0.txt)
   9 //
  10 // See http://www.boost.org/libs/intrusive for documentation.
  11 //
  12 /////////////////////////////////////////////////////////////////////////////
  13
  14 #ifndef BOOST_INTRUSIVE_LIST_HOOK_HPP
  15 #define BOOST_INTRUSIVE_LIST_HOOK_HPP
  16
  17 #include <boost/intrusive/detail/config_begin.hpp>
  18 #include <boost/intrusive/intrusive_fwd.hpp>
  19 #include <boost/intrusive/detail/utilities.hpp>
  20 #include <boost/intrusive/detail/list_node.hpp>
  21 #include <boost/intrusive/circular_list_algorithms.hpp>
  22 #include <boost/intrusive/options.hpp>
  23 #include <boost/intrusive/detail/generic_hook.hpp>
  24
  25 namespace boost {
  26 namespace intrusive {
  27
  28 /// @cond
  29 template<class VoidPointer>
  30 struct get_list_node_algo
  31 {
  32    typedef circular_list_algorithms<list_node_traits<VoidPointer> > type;
  33 };
  34 /// @endcond
  35
  36 //! Helper metafunction to define a \c \c list_base_hook that yields to the same
  37 //! type when the same options (either explicitly or implicitly) are used.
  38 #if defined(BOOST_INTRUSIVE_DOXYGEN_INVOKED) || defined(BOOST_INTRUSIVE_VARIADIC_TEMPLATES)
  39 template<class ...Options>
  40 #else
  41 template<class O1 = none, class O2 = none, class O3 = none>
  42 #endif
  43 struct make_list_base_hook
  44 {
  45    /// @cond
  46    typedef typename pack_options
  47       < hook_defaults,
  48       #if !defined(BOOST_INTRUSIVE_VARIADIC_TEMPLATES)
  49       O1, O2, O3
  50       #else
  51       Options...
  52       #endif
  53       >::type packed_options;
  54
  55    typedef detail::generic_hook
  56    < get_list_node_algo<typename packed_options::void_pointer>
  57    , typename packed_options::tag
  58    , packed_options::link_mode
  59    , detail::ListBaseHook
  60    > implementation_defined;
  61    /// @endcond
  62    typedef implementation_defined type;
  63 };
  64
  65 //! Derive a class from this hook in order to store objects of that class
  66 //! in an list.
  67 //!
  68 //! The hook admits the following options: \c tag<>, \c void_pointer<> and
  69 //! \c link_mode<>.
  70 //!
  71 //! \c tag<> defines a tag to identify the node.
  72 //! The same tag value can be used in different classes, but if a class is
  73 //! derived from more than one \c list_base_hook, then each \c list_base_hook needs its
  74 //! unique tag.
  75 //!
  76 //! \c link_mode<> will specify the linking mode of the hook (\c normal_link,
  77 //! \c auto_unlink or \c safe_link).
  78 //!
  79 //! \c void_pointer<> is the pointer type that will be used internally in the hook
  80 //! and the the container configured to use this hook.
  81 #if defined(BOOST_INTRUSIVE_DOXYGEN_INVOKED) || defined(BOOST_INTRUSIVE_VARIADIC_TEMPLATES)
  82 template<class ...Options>
  83 #else
  84 template<class O1, class O2, class O3>
  85 #endif
  86 class list_base_hook
  87    :  public make_list_base_hook
  88       #if !defined(BOOST_INTRUSIVE_VARIADIC_TEMPLATES)
  89       <O1, O2, O3>
  90       #else
  91       <Options...>
  92       #endif
  93       ::type
  94 {
  95    #if defined(BOOST_INTRUSIVE_DOXYGEN_INVOKED)
  96    //! <b>Effects</b>: If link_mode is \c auto_unlink or \c safe_link
  97    //!   initializes the node to an unlinked state.
  98    //!
  99    //! <b>Throws</b>: Nothing.
 100    list_base_hook();
 101
 102    //! <b>Effects</b>: If link_mode is \c auto_unlink or \c safe_link
 103    //!   initializes the node to an unlinked state. The argument is ignored.
 104    //!
 105    //! <b>Throws</b>: Nothing.
 106    //!
 107    //! <b>Rationale</b>: Providing a copy-constructor
 108    //!   makes classes using the hook STL-compliant without forcing the
 109    //!   user to do some additional work. \c swap can be used to emulate
 110    //!   move-semantics.
 111    list_base_hook(const list_base_hook& );
 112
 113    //! <b>Effects</b>: Empty function. The argument is ignored.
 114    //!
 115    //! <b>Throws</b>: Nothing.
 116    //!
 117    //! <b>Rationale</b>: Providing an assignment operator
 118    //!   makes classes using the hook STL-compliant without forcing the
 119    //!   user to do some additional work. \c swap can be used to emulate
 120    //!   move-semantics.
 121    list_base_hook& operator=(const list_base_hook& );
 122
 123    //! <b>Effects</b>: If link_mode is \c normal_link, the destructor does
 124    //!   nothing (ie. no code is generated). If link_mode is \c safe_link and the
 125    //!   object is stored in an list an assertion is raised. If link_mode is
 126    //!   \c auto_unlink and \c is_linked() is true, the node is unlinked.
 127    //!
 128    //! <b>Throws</b>: Nothing.
 129    ~list_base_hook();
 130
 131    //! <b>Effects</b>: Swapping two nodes swaps the position of the elements
 132    //!   related to those nodes in one or two containers. That is, if the node
 133    //!   this is part of the element e1, the node x is part of the element e2
 134    //!   and both elements are included in the containers s1 and s2, then after
 135    //!   the swap-operation e1 is in s2 at the position of e2 and e2 is in s1
 136    //!   at the position of e1. If one element is not in a container, then
 137    //!   after the swap-operation the other element is not in a container.
 138    //!   Iterators to e1 and e2 related to those nodes are invalidated.
 139    //!
 140    //! <b>Complexity</b>: Constant
 141    //!
 142    //! <b>Throws</b>: Nothing.
 143    void swap_nodes(list_base_hook &other);
 144
 145    //! <b>Precondition</b>: link_mode must be \c safe_link or \c auto_unlink.
 146    //!
 147    //! <b>Returns</b>: true, if the node belongs to a container, false
 148    //!   otherwise. This function can be used to test whether \c list::iterator_to
 149    //!   will return a valid iterator.
 150    //!
 151    //! <b>Complexity</b>: Constant
 152    bool is_linked() const;
 153
 154    //! <b>Effects</b>: Removes the node if it's inserted in a container.
 155    //!   This function is only allowed if link_mode is \c auto_unlink.
 156    //!
 157    //! <b>Throws</b>: Nothing.
 158    void unlink();
 159    #endif
 160 };
 161
 162 //! Helper metafunction to define a \c \c list_member_hook that yields to the same
 163 //! type when the same options (either explicitly or implicitly) are used.
 164 #if defined(BOOST_INTRUSIVE_DOXYGEN_INVOKED) || defined(BOOST_INTRUSIVE_VARIADIC_TEMPLATES)
 165 template<class ...Options>
 166 #else
 167 template<class O1 = none, class O2 = none, class O3 = none>
 168 #endif
 169 struct make_list_member_hook
 170 {
 171    /// @cond
 172    typedef typename pack_options
 173       < hook_defaults,
 174       #if !defined(BOOST_INTRUSIVE_VARIADIC_TEMPLATES)
 175       O1, O2, O3
 176       #else
 177       Options...
 178       #endif
 179       >::type packed_options;
 180
 181    typedef detail::generic_hook
 182    < get_list_node_algo<typename packed_options::void_pointer>
 183    , member_tag
 184    , packed_options::link_mode
 185    , detail::NoBaseHook
 186    > implementation_defined;
 187    /// @endcond
 188    typedef implementation_defined type;
 189 };
 190
 191 //! Store this hook in a class to be inserted
 192 //! in an list.
 193 //!
 194 //! The hook admits the following options: \c void_pointer<> and
 195 //! \c link_mode<>.
 196 //!
 197 //! \c link_mode<> will specify the linking mode of the hook (\c normal_link,
 198 //! \c auto_unlink or \c safe_link).
 199 //!
 200 //! \c void_pointer<> is the pointer type that will be used internally in the hook
 201 //! and the the container configured to use this hook.
 202 #if defined(BOOST_INTRUSIVE_DOXYGEN_INVOKED) || defined(BOOST_INTRUSIVE_VARIADIC_TEMPLATES)
 203 template<class ...Options>
 204 #else
 205 template<class O1, class O2, class O3>
 206 #endif
 207 class list_member_hook
 208    :  public make_list_member_hook
 209       #if !defined(BOOST_INTRUSIVE_VARIADIC_TEMPLATES)
 210       <O1, O2, O3>
 211       #else
 212       <Options...>
 213       #endif
 214       ::type
 215 {
 216    #if defined(BOOST_INTRUSIVE_DOXYGEN_INVOKED)
 217    //! <b>Effects</b>: If link_mode is \c auto_unlink or \c safe_link
 218    //!   initializes the node to an unlinked state.
 219    //!
 220    //! <b>Throws</b>: Nothing.
 221    list_member_hook();
 222
 223    //! <b>Effects</b>: If link_mode is \c auto_unlink or \c safe_link
 224    //!   initializes the node to an unlinked state. The argument is ignored.
 225    //!
 226    //! <b>Throws</b>: Nothing.
 227    //!
 228    //! <b>Rationale</b>: Providing a copy-constructor
 229    //!   makes classes using the hook STL-compliant without forcing the
 230    //!   user to do some additional work. \c swap can be used to emulate
 231    //!   move-semantics.
 232    list_member_hook(const list_member_hook& );
 233
 234    //! <b>Effects</b>: Empty function. The argument is ignored.
 235    //!
 236    //! <b>Throws</b>: Nothing.
 237    //!
 238    //! <b>Rationale</b>: Providing an assignment operator
 239    //!   makes classes using the hook STL-compliant without forcing the
 240    //!   user to do some additional work. \c swap can be used to emulate
 241    //!   move-semantics.
 242    list_member_hook& operator=(const list_member_hook& );
 243
 244    //! <b>Effects</b>: If link_mode is \c normal_link, the destructor does
 245    //!   nothing (ie. no code is generated). If link_mode is \c safe_link and the
 246    //!   object is stored in an list an assertion is raised. If link_mode is
 247    //!   \c auto_unlink and \c is_linked() is true, the node is unlinked.
 248    //!
 249    //! <b>Throws</b>: Nothing.
 250    ~list_member_hook();
 251
 252    //! <b>Effects</b>: Swapping two nodes swaps the position of the elements
 253    //!   related to those nodes in one or two containers. That is, if the node
 254    //!   this is part of the element e1, the node x is part of the element e2
 255    //!   and both elements are included in the containers s1 and s2, then after
 256    //!   the swap-operation e1 is in s2 at the position of e2 and e2 is in s1
 257    //!   at the position of e1. If one element is not in a container, then
 258    //!   after the swap-operation the other element is not in a container.
 259    //!   Iterators to e1 and e2 related to those nodes are invalidated.
 260    //!
 261    //! <b>Complexity</b>: Constant
 262    //!
 263    //! <b>Throws</b>: Nothing.
 264    void swap_nodes(list_member_hook &other);
 265
 266    //! <b>Precondition</b>: link_mode must be \c safe_link or \c auto_unlink.
 267    //!
 268    //! <b>Returns</b>: true, if the node belongs to a container, false
 269    //!   otherwise. This function can be used to test whether \c list::iterator_to
 270    //!   will return a valid iterator.
 271    //!
 272    //! <b>Complexity</b>: Constant
 273    bool is_linked() const;
 274
 275    //! <b>Effects</b>: Removes the node if it's inserted in a container.
 276    //!   This function is only allowed if link_mode is \c auto_unlink.
 277    //!
 278    //! <b>Throws</b>: Nothing.
 279    void unlink();
 280    #endif
 281 };
 282
 283 } //namespace intrusive
 284 } //namespace boost
 285
 286 #include <boost/intrusive/detail/config_end.hpp>
 287
 288 #endif //BOOST_INTRUSIVE_LIST_HOOK_HPP