1 // Copyright (C) 2022 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_NUMERIC_POSTING_LIST_INTEGER_INDEX_ACCESSOR_H_ 16 #define ICING_INDEX_NUMERIC_POSTING_LIST_INTEGER_INDEX_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/numeric/integer-index-data.h" 29 #include "icing/index/numeric/posting-list-integer-index-serializer.h" 30 31 namespace icing { 32 namespace lib { 33 34 // TODO(b/259743562): Refactor PostingListAccessor derived classes 35 36 // This class is used to provide a simple abstraction for adding integer index 37 // data to posting lists. PostingListIntegerIndexAccessor handles: 38 // 1) selection of properly-sized posting lists for the accumulated integer 39 // index data during Finalize() 40 // 2) chaining of max-sized posting lists. 41 class PostingListIntegerIndexAccessor : public PostingListAccessor { 42 public: 43 // Creates an empty PostingListIntegerIndexAccessor. 44 // 45 // RETURNS: 46 // - On success, a valid instance of PostingListIntegerIndexAccessor 47 // - INVALID_ARGUMENT error if storage has an invalid block_size. 48 static libtextclassifier3::StatusOr< 49 std::unique_ptr<PostingListIntegerIndexAccessor>> 50 Create(FlashIndexStorage* storage, 51 PostingListIntegerIndexSerializer* serializer); 52 53 // Creates a PostingListIntegerIndexAccessor with an existing posting list 54 // identified by existing_posting_list_id. 55 // 56 // RETURNS: 57 // - On success, a valid instance of PostingListIntegerIndexAccessor 58 // - INVALID_ARGUMENT if storage has an invalid block_size. 59 static libtextclassifier3::StatusOr< 60 std::unique_ptr<PostingListIntegerIndexAccessor>> 61 CreateFromExisting(FlashIndexStorage* storage, 62 PostingListIntegerIndexSerializer* serializer, 63 PostingListIdentifier existing_posting_list_id); 64 GetSerializer()65 PostingListSerializer* GetSerializer() override { return serializer_; } 66 67 // Retrieves the next batch of data in the posting list chain. 68 // 69 // RETURNS: 70 // - On success, a vector of integer index data in the posting list chain 71 // - FAILED_PRECONDITION_ERROR if called on an instance that was created via 72 // Create. 73 // - INTERNAL_ERROR if unable to read the next posting list in the chain or 74 // if the posting list has been corrupted somehow. 75 libtextclassifier3::StatusOr<std::vector<IntegerIndexData>> 76 GetNextDataBatch(); 77 78 // Retrieves all data from the posting list chain and frees all posting 79 // list(s). 80 // 81 // RETURNS: 82 // - On success, a vector of integer index data in the posting list chain 83 // - FAILED_PRECONDITION_ERROR if called on an instance that was created via 84 // Create. 85 // - INTERNAL_ERROR if unable to read the next posting list in the chain or 86 // if the posting list has been corrupted somehow. 87 libtextclassifier3::StatusOr<std::vector<IntegerIndexData>> 88 GetAllDataAndFree(); 89 90 // Prepends one data. This may result in flushing the posting list to disk (if 91 // the PostingListIntegerIndexAccessor holds a max-sized posting list that 92 // is full) or freeing a pre-existing posting list if it is too small to fit 93 // all data necessary. 94 // 95 // RETURNS: 96 // - OK, on success 97 // - INVALID_ARGUMENT if !data.is_valid() or if data is greater than the 98 // previously added data. 99 // - RESOURCE_EXHAUSTED error if unable to grow the index to allocate a new 100 // posting list. 101 libtextclassifier3::Status PrependData(const IntegerIndexData& data); 102 103 private: PostingListIntegerIndexAccessor(FlashIndexStorage * storage,PostingListUsed in_memory_posting_list,PostingListIntegerIndexSerializer * serializer)104 explicit PostingListIntegerIndexAccessor( 105 FlashIndexStorage* storage, PostingListUsed in_memory_posting_list, 106 PostingListIntegerIndexSerializer* serializer) 107 : PostingListAccessor(storage, std::move(in_memory_posting_list)), 108 serializer_(serializer) {} 109 110 // Retrieves the next batch of data in the posting list chain. 111 // 112 // - free_posting_list: a boolean flag indicating whether freeing all posting 113 // lists after retrieving batch data. 114 // 115 // RETURNS: 116 // - On success, a vector of integer index data in the posting list chain 117 // - FAILED_PRECONDITION_ERROR if called on an instance that was created via 118 // Create. 119 // - INTERNAL_ERROR if unable to read the next posting list in the chain or 120 // if the posting list has been corrupted somehow. 121 libtextclassifier3::StatusOr<std::vector<IntegerIndexData>> 122 GetNextDataBatchImpl(bool free_posting_list); 123 124 PostingListIntegerIndexSerializer* serializer_; // Does not own. 125 }; 126 127 } // namespace lib 128 } // namespace icing 129 130 #endif // ICING_INDEX_NUMERIC_POSTING_LIST_INTEGER_INDEX_ACCESSOR_H_ 131