1 /* Copyright (c) 2010, 2021, Oracle and/or its affiliates.
2 
3    This program is free software; you can redistribute it and/or modify
4    it under the terms of the GNU General Public License, version 2.0,
5    as published by the Free Software Foundation.
6 
7    This program is also distributed with certain software (including
8    but not limited to OpenSSL) that is licensed under separate terms,
9    as designated in a particular file or component or in included license
10    documentation.  The authors of MySQL hereby grant you an additional
11    permission to link the program and your derivative works with the
12    separately licensed software that they have included with MySQL.
13 
14    This program is distributed in the hope that it will be useful,
15    but WITHOUT ANY WARRANTY; without even the implied warranty of
16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17    GNU General Public License, version 2.0, for more details.
18 
19    You should have received a copy of the GNU General Public License
20    along with this program; if not, write to the Free Software
21    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA */
22 
23 #ifndef BOUNDED_QUEUE_INCLUDED
24 #define BOUNDED_QUEUE_INCLUDED
25 
26 #include "my_global.h"
27 #include "my_base.h"
28 #include "my_sys.h"
29 #include "mysys_err.h"
30 #include "priority_queue.h"
31 #include "malloc_allocator.h"
32 
33 /**
34   A priority queue with a fixed, limited size.
35 
36   This is a wrapper on top of Priority_queue.
37   It keeps the top-N elements which are inserted.
38 
39   Elements of type Element_type are pushed into the queue.
40   For each element, we call a user-supplied Key_generator::make_sortkey(),
41   to generate a key of type Key_type for the element.
42   Instances of Key_type are compared with the user-supplied Key_compare.
43 
44   Pointers to the top-N elements are stored in the sort_keys array given
45   to the init() function below. To access elements in sorted order,
46   sort the array and access it sequentially.
47  */
48 template<typename Element_type,
49          typename Key_type,
50          typename Key_generator,
51          typename Key_compare = std::less<Key_type>
52         >
53 class Bounded_queue
54 {
55 public:
56   typedef Priority_queue<Key_type,
57                          std::vector<Key_type, Malloc_allocator<Key_type> >,
58                          Key_compare> Queue_type;
59 
60   typedef typename Queue_type::allocator_type allocator_type;
61 
62   explicit Bounded_queue(const allocator_type
63                          &alloc = allocator_type(PSI_NOT_INSTRUMENTED))
m_queue(Key_compare (),alloc)64     : m_queue(Key_compare(), alloc),
65       m_sort_keys(NULL),
66       m_sort_param(NULL)
67   {}
68 
69   /**
70     Initialize the queue.
71 
72     @param max_elements   The size of the queue.
73     @param sort_param     Sort parameters. We call sort_param->make_sortkey()
74                           to generate keys for elements.
75     @param[in,out] sort_keys Array of keys to sort.
76                              Must be initialized by caller.
77                              Will be filled with pointers to the top-N elements.
78 
79     @retval false OK, true Could not allocate memory.
80 
81     We do *not* take ownership of any of the input pointer arguments.
82    */
init(ha_rows max_elements,Key_generator * sort_param,Key_type * sort_keys)83   bool init(ha_rows max_elements,
84             Key_generator *sort_param,
85             Key_type *sort_keys)
86   {
87     m_sort_keys= sort_keys;
88     m_sort_param= sort_param;
89     DBUG_EXECUTE_IF("bounded_queue_init_fail",
90                     my_error(EE_OUTOFMEMORY, MYF(ME_FATALERROR), 42);
91                     return true;);
92 
93     // We allocate space for one extra element, for replace when queue is full.
94     if (m_queue.reserve(max_elements + 1))
95       return true;
96     m_queue.m_compare_length= sort_param->compare_length();
97     return false;
98   }
99 
100   /**
101     Pushes an element on the queue.
102     If the queue is already full, we discard one element.
103     Calls m_sort_param::make_sortkey() to generate a key for the element.
104 
105     @param element        The element to be pushed.
106    */
push(Element_type element)107   void push(Element_type element)
108   {
109     if (m_queue.size() == m_queue.capacity())
110     {
111       const Key_type &pq_top= m_queue.top();
112       m_sort_param->make_sortkey(pq_top, element);
113       m_queue.update_top();
114     } else {
115       m_sort_param->make_sortkey(m_sort_keys[m_queue.size()], element);
116       m_queue.push(m_sort_keys[m_queue.size()]);
117     }
118   }
119 
120   /**
121     The number of elements in the queue.
122    */
num_elements()123   size_t num_elements() const { return m_queue.size(); }
124 
125 private:
126   Queue_type         m_queue;
127   Key_type          *m_sort_keys;
128   Key_generator     *m_sort_param;
129 };
130 
131 #endif  // BOUNDED_QUEUE_INCLUDED
132