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