1 /**
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements. See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership. The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License. You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 */
19
20 package org.apache.hadoop.hbase.regionserver;
21
22 import java.io.IOException;
23 import java.util.Comparator;
24 import java.util.List;
25 import java.util.PriorityQueue;
26
27 import org.apache.hadoop.classification.InterfaceAudience;
28 import org.apache.hadoop.hbase.KeyValue;
29 import org.apache.hadoop.hbase.KeyValue.KVComparator;
30
31 /**
32 * Implements a heap merge across any number of KeyValueScanners.
33 * <p>
34 * Implements KeyValueScanner itself.
35 * <p>
36 * This class is used at the Region level to merge across Stores
37 * and at the Store level to merge across the memstore and StoreFiles.
38 * <p>
39 * In the Region case, we also need InternalScanner.next(List), so this class
40 * also implements InternalScanner. WARNING: As is, if you try to use this
41 * as an InternalScanner at the Store level, you will get runtime exceptions.
42 */
43 @InterfaceAudience.Private
44 public class KeyValueHeap extends NonLazyKeyValueScanner
45 implements KeyValueScanner, InternalScanner {
46 private PriorityQueue<KeyValueScanner> heap = null;
47
48 /**
49 * The current sub-scanner, i.e. the one that contains the next key/value
50 * to return to the client. This scanner is NOT included in {@link #heap}
51 * (but we frequently add it back to the heap and pull the new winner out).
52 * We maintain an invariant that the current sub-scanner has already done
53 * a real seek, and that current.peek() is always a real key/value (or null)
54 * except for the fake last-key-on-row-column supplied by the multi-column
55 * Bloom filter optimization, which is OK to propagate to StoreScanner. In
56 * order to ensure that, always use {@link #pollRealKV()} to update current.
57 */
58 private KeyValueScanner current = null;
59
60 private KVScannerComparator comparator;
61
62 /**
63 * Constructor. This KeyValueHeap will handle closing of passed in
64 * KeyValueScanners.
65 * @param scanners
66 * @param comparator
67 */
68 public KeyValueHeap(List<? extends KeyValueScanner> scanners,
69 KVComparator comparator) throws IOException {
70 this.comparator = new KVScannerComparator(comparator);
71 if (!scanners.isEmpty()) {
72 this.heap = new PriorityQueue<KeyValueScanner>(scanners.size(),
73 this.comparator);
74 for (KeyValueScanner scanner : scanners) {
75 if (scanner.peek() != null) {
76 this.heap.add(scanner);
77 } else {
78 scanner.close();
79 }
80 }
81 this.current = pollRealKV();
82 }
83 }
84
85 public KeyValue peek() {
86 if (this.current == null) {
87 return null;
88 }
89 return this.current.peek();
90 }
91
92 public KeyValue next() throws IOException {
93 if(this.current == null) {
94 return null;
95 }
96 KeyValue kvReturn = this.current.next();
97 KeyValue kvNext = this.current.peek();
98 if (kvNext == null) {
99 this.current.close();
100 this.current = pollRealKV();
101 } else {
102 KeyValueScanner topScanner = this.heap.peek();
103 if (topScanner == null ||
104 this.comparator.compare(kvNext, topScanner.peek()) >= 0) {
105 this.heap.add(this.current);
106 this.current = pollRealKV();
107 }
108 }
109 return kvReturn;
110 }
111
112 /**
113 * Gets the next row of keys from the top-most scanner.
114 * <p>
115 * This method takes care of updating the heap.
116 * <p>
117 * This can ONLY be called when you are using Scanners that implement
118 * InternalScanner as well as KeyValueScanner (a {@link StoreScanner}).
119 * @param result
120 * @param limit
121 * @return true if there are more keys, false if all scanners are done
122 */
123 public boolean next(List<KeyValue> result, int limit) throws IOException {
124 if (this.current == null) {
125 return false;
126 }
127 InternalScanner currentAsInternal = (InternalScanner)this.current;
128 boolean mayContainMoreRows = currentAsInternal.next(result, limit);
129 KeyValue pee = this.current.peek();
130 /*
131 * By definition, any InternalScanner must return false only when it has no
132 * further rows to be fetched. So, we can close a scanner if it returns
133 * false. All existing implementations seem to be fine with this. It is much
134 * more efficient to close scanners which are not needed than keep them in
135 * the heap. This is also required for certain optimizations.
136 */
137 if (pee == null || !mayContainMoreRows) {
138 this.current.close();
139 } else {
140 this.heap.add(this.current);
141 }
142 this.current = pollRealKV();
143 return (this.current != null);
144 }
145
146 /**
147 * Gets the next row of keys from the top-most scanner.
148 * <p>
149 * This method takes care of updating the heap.
150 * <p>
151 * This can ONLY be called when you are using Scanners that implement
152 * InternalScanner as well as KeyValueScanner (a {@link StoreScanner}).
153 * @param result
154 * @return true if there are more keys, false if all scanners are done
155 */
156 public boolean next(List<KeyValue> result) throws IOException {
157 return next(result, -1);
158 }
159
160 private static class KVScannerComparator implements Comparator<KeyValueScanner> {
161 private KVComparator kvComparator;
162 /**
163 * Constructor
164 * @param kvComparator
165 */
166 public KVScannerComparator(KVComparator kvComparator) {
167 this.kvComparator = kvComparator;
168 }
169 public int compare(KeyValueScanner left, KeyValueScanner right) {
170 int comparison = compare(left.peek(), right.peek());
171 if (comparison != 0) {
172 return comparison;
173 } else {
174 // Since both the keys are exactly the same, we break the tie in favor
175 // of the key which came latest.
176 long leftSequenceID = left.getSequenceID();
177 long rightSequenceID = right.getSequenceID();
178 if (leftSequenceID > rightSequenceID) {
179 return -1;
180 } else if (leftSequenceID < rightSequenceID) {
181 return 1;
182 } else {
183 return 0;
184 }
185 }
186 }
187 /**
188 * Compares two KeyValue
189 * @param left
190 * @param right
191 * @return less than 0 if left is smaller, 0 if equal etc..
192 */
193 public int compare(KeyValue left, KeyValue right) {
194 return this.kvComparator.compare(left, right);
195 }
196 /**
197 * @return KVComparator
198 */
199 public KVComparator getComparator() {
200 return this.kvComparator;
201 }
202 }
203
204 public void close() {
205 if (this.current != null) {
206 this.current.close();
207 }
208 if (this.heap != null) {
209 KeyValueScanner scanner;
210 while ((scanner = this.heap.poll()) != null) {
211 scanner.close();
212 }
213 }
214 }
215
216 /**
217 * Seeks all scanners at or below the specified seek key. If we earlied-out
218 * of a row, we may end up skipping values that were never reached yet.
219 * Rather than iterating down, we want to give the opportunity to re-seek.
220 * <p>
221 * As individual scanners may run past their ends, those scanners are
222 * automatically closed and removed from the heap.
223 * <p>
224 * This function (and {@link #reseek(KeyValue)}) does not do multi-column
225 * Bloom filter and lazy-seek optimizations. To enable those, call
226 * {@link #requestSeek(KeyValue, boolean, boolean)}.
227 * @param seekKey KeyValue to seek at or after
228 * @return true if KeyValues exist at or after specified key, false if not
229 * @throws IOException
230 */
231 @Override
232 public boolean seek(KeyValue seekKey) throws IOException {
233 return generalizedSeek(false, // This is not a lazy seek
234 seekKey,
235 false, // forward (false: this is not a reseek)
236 false); // Not using Bloom filters
237 }
238
239 /**
240 * This function is identical to the {@link #seek(KeyValue)} function except
241 * that scanner.seek(seekKey) is changed to scanner.reseek(seekKey).
242 */
243 @Override
244 public boolean reseek(KeyValue seekKey) throws IOException {
245 return generalizedSeek(false, // This is not a lazy seek
246 seekKey,
247 true, // forward (true because this is reseek)
248 false); // Not using Bloom filters
249 }
250
251 /**
252 * {@inheritDoc}
253 */
254 @Override
255 public boolean requestSeek(KeyValue key, boolean forward,
256 boolean useBloom) throws IOException {
257 return generalizedSeek(true, key, forward, useBloom);
258 }
259
260 /**
261 * @param isLazy whether we are trying to seek to exactly the given row/col.
262 * Enables Bloom filter and most-recent-file-first optimizations for
263 * multi-column get/scan queries.
264 * @param seekKey key to seek to
265 * @param forward whether to seek forward (also known as reseek)
266 * @param useBloom whether to optimize seeks using Bloom filters
267 */
268 private boolean generalizedSeek(boolean isLazy, KeyValue seekKey,
269 boolean forward, boolean useBloom) throws IOException {
270 if (!isLazy && useBloom) {
271 throw new IllegalArgumentException("Multi-column Bloom filter " +
272 "optimization requires a lazy seek");
273 }
274
275 if (current == null) {
276 return false;
277 }
278 heap.add(current);
279 current = null;
280
281 KeyValueScanner scanner;
282 while ((scanner = heap.poll()) != null) {
283 KeyValue topKey = scanner.peek();
284 if (comparator.getComparator().compare(seekKey, topKey) <= 0) {
285 // Top KeyValue is at-or-after Seek KeyValue. We only know that all
286 // scanners are at or after seekKey (because fake keys of
287 // scanners where a lazy-seek operation has been done are not greater
288 // than their real next keys) but we still need to enforce our
289 // invariant that the top scanner has done a real seek. This way
290 // StoreScanner and RegionScanner do not have to worry about fake keys.
291 heap.add(scanner);
292 current = pollRealKV();
293 return current != null;
294 }
295
296 boolean seekResult;
297 if (isLazy && heap.size() > 0) {
298 // If there is only one scanner left, we don't do lazy seek.
299 seekResult = scanner.requestSeek(seekKey, forward, useBloom);
300 } else {
301 seekResult = NonLazyKeyValueScanner.doRealSeek(
302 scanner, seekKey, forward);
303 }
304
305 if (!seekResult) {
306 scanner.close();
307 } else {
308 heap.add(scanner);
309 }
310 }
311
312 // Heap is returning empty, scanner is done
313 return false;
314 }
315
316 /**
317 * Fetches the top sub-scanner from the priority queue, ensuring that a real
318 * seek has been done on it. Works by fetching the top sub-scanner, and if it
319 * has not done a real seek, making it do so (which will modify its top KV),
320 * putting it back, and repeating this until success. Relies on the fact that
321 * on a lazy seek we set the current key of a StoreFileScanner to a KV that
322 * is not greater than the real next KV to be read from that file, so the
323 * scanner that bubbles up to the top of the heap will have global next KV in
324 * this scanner heap if (1) it has done a real seek and (2) its KV is the top
325 * among all top KVs (some of which are fake) in the scanner heap.
326 */
327 private KeyValueScanner pollRealKV() throws IOException {
328 KeyValueScanner kvScanner = heap.poll();
329 if (kvScanner == null) {
330 return null;
331 }
332
333 while (kvScanner != null && !kvScanner.realSeekDone()) {
334 if (kvScanner.peek() != null) {
335 kvScanner.enforceSeek();
336 KeyValue curKV = kvScanner.peek();
337 if (curKV != null) {
338 KeyValueScanner nextEarliestScanner = heap.peek();
339 if (nextEarliestScanner == null) {
340 // The heap is empty. Return the only possible scanner.
341 return kvScanner;
342 }
343
344 // Compare the current scanner to the next scanner. We try to avoid
345 // putting the current one back into the heap if possible.
346 KeyValue nextKV = nextEarliestScanner.peek();
347 if (nextKV == null || comparator.compare(curKV, nextKV) < 0) {
348 // We already have the scanner with the earliest KV, so return it.
349 return kvScanner;
350 }
351
352 // Otherwise, put the scanner back into the heap and let it compete
353 // against all other scanners (both those that have done a "real
354 // seek" and a "lazy seek").
355 heap.add(kvScanner);
356 } else {
357 // Close the scanner because we did a real seek and found out there
358 // are no more KVs.
359 kvScanner.close();
360 }
361 } else {
362 // Close the scanner because it has already run out of KVs even before
363 // we had to do a real seek on it.
364 kvScanner.close();
365 }
366 kvScanner = heap.poll();
367 }
368
369 return kvScanner;
370 }
371
372 /**
373 * @return the current Heap
374 */
375 public PriorityQueue<KeyValueScanner> getHeap() {
376 return this.heap;
377 }
378
379 @Override
380 public long getSequenceID() {
381 return 0;
382 }
383
384 KeyValueScanner getCurrentForTesting() {
385 return current;
386 }
387 }