ACE/ace/Intrusive_List.h

   1 /* -*- C++ -*- */
   2
   3 //=============================================================================
   4 /**
   5  *  @file Intrusive_List.h
   6  *
   7  *  @author Carlos O'Ryan <coryan@uci.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_INTRUSIVE_LIST_H
  12 #define ACE_INTRUSIVE_LIST_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include /**/ "ace/config-lite.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  22
  23 /**
  24  * @class ACE_Intrusive_List
  25  *
  26  * @brief Implement an intrusive double linked list
  27  *
  28  * Intrusive lists assume that the elements they contain the pointers
  29  * required to build the list.  They are useful as light-weight
  30  * containers and free-lists.
  31  *
  32  * The template argument T must implement the following methods:
  33  *
  34  * - T* T::next () const;
  35  * - void T::next (T *);
  36  * - T* T::prev () const;
  37  * - void T::prev (T* );
  38  *
  39  * A simple way to satisfy the Intrusive_List requirements would be to
  40  * implement a helper class:
  41  *
  42  * class My_Object : public ACE_Intrusive_List_Node<My_Object> {<BR>
  43  * ....<BR>
  44  * };<BR>
  45  *
  46  * typedef ACE_Intrusive_List<My_Object> My_Object_List;
  47  *
  48  * However, ACE is supported on platforms that would surely get
  49  * confused using such templates.
  50  *
  51  * @todo The ACE_Message_Queue is an example of an intrusive list (or
  52  * queue) but it is not implemented in terms of this class.
  53  */
  54 template <class T>
  55 class ACE_Intrusive_List
  56 {
  57 public:
  58   /// Constructor.  Use user specified allocation strategy
  59   /// if specified.
  60   ACE_Intrusive_List () = default;
  61
  62   /// Destructor.
  63   ~ACE_Intrusive_List () = default;
  64
  65   // = Check boundary conditions.
  66
  67   /// Returns true if the container is empty, otherwise returns false.
  68   bool is_empty () const;
  69
  70   /// Insert an element at the beginning of the list
  71   void push_front (T *node);
  72
  73   /// Insert an element at the end of the list
  74   void push_back (T *node);
  75
  76   /// Remove the element at the beginning of the list
  77   T *pop_front ();
  78
  79   /// Remove the element at the end of the list
  80   T *pop_back ();
  81
  82   /// Get the element at the head of the queue
  83   T *head () const;
  84
  85   /// Get the element at the tail of the queue
  86   T *tail () const;
  87
  88   /// Remove a element from the list
  89   /**
  90    * Verify that the element is still in the list before removing it.
  91    */
  92   void remove (T *node);
  93
  94   /// Swap two lists
  95   void swap(ACE_Intrusive_List<T> & rhs);
  96
  97   /// Remove a element from the list without checking
  98   /**
  99    * No attempts are performed to check if T* really belongs to the
 100    * list.  The effects of removing an invalid element are unspecified
 101    */
 102   void unsafe_remove (T *node);
 103
 104 private:
 105   /** @name Disallow copying
 106    *
 107    */
 108   //@{
 109   ACE_Intrusive_List (const ACE_Intrusive_List<T> &);
 110   ACE_Intrusive_List<T>& operator= (const ACE_Intrusive_List<T> &);
 111   //@}
 112
 113 private:
 114   /// Head of the list
 115   T *head_ {};
 116
 117   /// Tail of the list
 118   T *tail_ {};
 119 };
 120
 121 ACE_END_VERSIONED_NAMESPACE_DECL
 122
 123 #if defined (__ACE_INLINE__)
 124 #include "ace/Intrusive_List.inl"
 125 #endif /* __ACE_INLINE__ */
 126
 127 #include "ace/Intrusive_List.cpp"
 128
 129 #include /**/ "ace/post.h"
 130 #endif /* ACE_INTRUSIVE_LIST_H */