1 // Copyright (C) 2019 Google LLC 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef ICING_INDEX_POSTING_LIST_HIT_ACCESSOR_H_ 16 #define ICING_INDEX_POSTING_LIST_HIT_ACCESSOR_H_ 17 18 #include <cstdint> 19 #include <memory> 20 #include <vector> 21 22 #include "icing/text_classifier/lib3/utils/base/status.h" 23 #include "icing/text_classifier/lib3/utils/base/statusor.h" 24 #include "icing/file/posting_list/flash-index-storage.h" 25 #include "icing/file/posting_list/posting-list-accessor.h" 26 #include "icing/file/posting_list/posting-list-identifier.h" 27 #include "icing/file/posting_list/posting-list-used.h" 28 #include "icing/index/hit/hit.h" 29 #include "icing/index/main/posting-list-hit-serializer.h" 30 31 namespace icing { 32 namespace lib { 33 34 // This class is used to provide a simple abstraction for adding hits to posting 35 // lists. PostingListHitAccessor handles 1) selection of properly-sized posting 36 // lists for the accumulated hits during Finalize() and 2) chaining of max-sized 37 // posting lists. 38 class PostingListHitAccessor : public PostingListAccessor { 39 public: 40 // Creates an empty PostingListHitAccessor. 41 // 42 // RETURNS: 43 // - On success, a valid unique_ptr instance of PostingListHitAccessor 44 // - INVALID_ARGUMENT error if storage has an invalid block_size. 45 static libtextclassifier3::StatusOr<std::unique_ptr<PostingListHitAccessor>> 46 Create(FlashIndexStorage* storage, PostingListHitSerializer* serializer); 47 48 // Create a PostingListHitAccessor with an existing posting list identified by 49 // existing_posting_list_id. 50 // 51 // The PostingListHitAccessor will add hits to this posting list until it is 52 // necessary either to 1) chain the posting list (if it is max-sized) or 2) 53 // move its hits to a larger posting list. 54 // 55 // RETURNS: 56 // - On success, a valid unique_ptr instance of PostingListHitAccessor 57 // - INVALID_ARGUMENT if storage has an invalid block_size. 58 static libtextclassifier3::StatusOr<std::unique_ptr<PostingListHitAccessor>> 59 CreateFromExisting(FlashIndexStorage* storage, 60 PostingListHitSerializer* serializer, 61 PostingListIdentifier existing_posting_list_id); 62 GetSerializer()63 PostingListSerializer* GetSerializer() override { return serializer_; } 64 65 // Retrieve the next batch of hits for the posting list chain 66 // 67 // RETURNS: 68 // - On success, a vector of hits in the posting list chain 69 // - INTERNAL if called on an instance of PostingListHitAccessor that was 70 // created via PostingListHitAccessor::Create, if unable to read the next 71 // posting list in the chain or if the posting list has been corrupted 72 // somehow. 73 libtextclassifier3::StatusOr<std::vector<Hit>> GetNextHitsBatch(); 74 75 // Prepend one hit. This may result in flushing the posting list to disk (if 76 // the PostingListHitAccessor holds a max-sized posting list that is full) or 77 // freeing a pre-existing posting list if it is too small to fit all hits 78 // necessary. 79 // 80 // RETURNS: 81 // - OK, on success 82 // - INVALID_ARGUMENT if !hit.is_valid() or if hit is not less than the 83 // previously added hit. 84 // - RESOURCE_EXHAUSTED error if unable to grow the index to allocate a new 85 // posting list. 86 libtextclassifier3::Status PrependHit(const Hit& hit); 87 88 private: PostingListHitAccessor(FlashIndexStorage * storage,PostingListHitSerializer * serializer,PostingListUsed in_memory_posting_list)89 explicit PostingListHitAccessor(FlashIndexStorage* storage, 90 PostingListHitSerializer* serializer, 91 PostingListUsed in_memory_posting_list) 92 : PostingListAccessor(storage, std::move(in_memory_posting_list)), 93 serializer_(serializer) {} 94 95 PostingListHitSerializer* serializer_; // Does not own. 96 }; 97 98 } // namespace lib 99 } // namespace icing 100 101 #endif // ICING_INDEX_POSTING_LIST_HIT_ACCESSOR_H_ 102