Create file open hints on IOContext to replace ReadAdvice

lucene/backward-codecs/src/java/org/apache/lucene/backward_codecs/lucene50/Lucene50CompoundReader.java

@@ -170,7 +170,7 @@ public IndexInput openInput(String name, IOContext context) throws IOException {
               + entries.keySet()
               + ")");
     }
-    return handle.slice(name, entry.offset, entry.length, context.readAdvice());
+    return handle.slice(name, entry.offset, entry.length, context);
   }
 
   /** Returns an array of strings, one for each file in the directory. */

lucene/codecs/src/java/org/apache/lucene/codecs/simpletext/SimpleTextCompoundFormat.java

@@ -137,10 +137,7 @@ public IndexInput openInput(String name, IOContext context) throws IOException {
         ensureOpen();
         int index = getIndex(name);
         return in.slice(
-            name,
-            startOffsets[index],
-            endOffsets[index] - startOffsets[index],
-            context.readAdvice());
+            name, startOffsets[index], endOffsets[index] - startOffsets[index], context);
       }
 
       @Override

lucene/core/src/java/org/apache/lucene/codecs/lucene90/Lucene90CompoundReader.java

@@ -169,7 +169,7 @@ public IndexInput openInput(String name, IOContext context) throws IOException {
               + entries.keySet()
               + ")");
     }
-    return handle.slice(name, entry.offset, entry.length, context.readAdvice());
+    return handle.slice(name, entry.offset, entry.length, context);
   }
 
   /** Returns an array of strings, one for each file in the directory. */

lucene/core/src/java/org/apache/lucene/index/DocumentsWriterPerThread.java

@@ -415,7 +415,7 @@ FlushedSegment flush(DocumentsWriter.FlushNotifications flushNotifications) thro
             segmentInfo,
             fieldInfos.finish(),
             pendingUpdates,
-            new IOContext(new FlushInfo(numDocsInRAM, lastCommittedBytesUsed)));
+            IOContext.flush(new FlushInfo(numDocsInRAM, lastCommittedBytesUsed)));
     final double startMBUsed = lastCommittedBytesUsed / 1024. / 1024.;
 
     // Apply delete-by-docID now (delete-byDocID only
@@ -599,7 +599,7 @@ void sealFlushedSegment(
     IndexWriter.setDiagnostics(newSegment.info, IndexWriter.SOURCE_FLUSH);
 
     IOContext context =
-        new IOContext(new FlushInfo(newSegment.info.maxDoc(), newSegment.sizeInBytes()));
+        IOContext.flush(new FlushInfo(newSegment.info.maxDoc(), newSegment.sizeInBytes()));
 
     boolean success = false;
     try {

lucene/core/src/java/org/apache/lucene/index/IndexWriter.java

@@ -3077,7 +3077,7 @@ public long addIndexes(Directory... dirs) throws IOException {
             }
 
             IOContext context =
-                new IOContext(new FlushInfo(info.info.maxDoc(), info.sizeInBytes()));
+                IOContext.flush(new FlushInfo(info.info.maxDoc(), info.sizeInBytes()));
 
             FieldInfos fis = readFieldInfos(info);
             for (FieldInfo fi : fis) {
@@ -3419,7 +3419,7 @@ public void addIndexesReaderMerge(MergePolicy.OneMerge merge) throws IOException
     testReserveDocs(numDocs);
 
     final IOContext context =
-        new IOContext(
+        IOContext.merge(
             new MergeInfo(Math.toIntExact(numDocs), -1, false, UNBOUNDED_MAX_MERGE_SEGMENTS));
 
     TrackingDirectoryWrapper trackingDir = new TrackingDirectoryWrapper(mergeDirectory);
@@ -3969,7 +3969,7 @@ public void setMergeInfo(SegmentCommitInfo info) {
       boolean closeReaders = true;
       try {
         for (MergePolicy.OneMerge merge : pointInTimeMerges.merges) {
-          IOContext context = new IOContext(merge.getStoreMergeInfo());
+          IOContext context = IOContext.merge(merge.getStoreMergeInfo());
           merge.initMergeReaders(
               sci -> {
                 final ReadersAndUpdates rld = getPooledInstance(sci, true);
@@ -5158,7 +5158,7 @@ private int mergeMiddle(MergePolicy.OneMerge merge, MergePolicy mergePolicy) thr
     merge.checkAborted();
 
     Directory mergeDirectory = mergeScheduler.wrapForMerge(merge, directory);
-    IOContext context = new IOContext(merge.getStoreMergeInfo());
+    IOContext context = IOContext.merge(merge.getStoreMergeInfo());
 
     final TrackingDirectoryWrapper dirWrapper = new TrackingDirectoryWrapper(mergeDirectory);
 

lucene/core/src/java/org/apache/lucene/index/ReadersAndUpdates.java

@@ -321,7 +321,7 @@ private synchronized void handleDVUpdates(
       }
       final long nextDocValuesGen = info.getNextDocValuesGen();
       final String segmentSuffix = Long.toString(nextDocValuesGen, Character.MAX_RADIX);
-      final IOContext updatesContext = new IOContext(new FlushInfo(info.info.maxDoc(), bytes));
+      final IOContext updatesContext = IOContext.flush(new FlushInfo(info.info.maxDoc(), bytes));
       final FieldInfo fieldInfo = infos.fieldInfo(field);
       assert fieldInfo != null;
       fieldInfo.setDocValuesGen(nextDocValuesGen);
@@ -536,7 +536,7 @@ private synchronized Set<String> writeFieldInfosGen(
     // HEADER + FOOTER: 40
     // 90 bytes per-field (over estimating long name and attributes map)
     final long estInfosSize = 40 + 90L * fieldInfos.size();
-    final IOContext infosContext = new IOContext(new FlushInfo(info.info.maxDoc(), estInfosSize));
+    final IOContext infosContext = IOContext.flush(new FlushInfo(info.info.maxDoc(), estInfosSize));
     // separately also track which files were created for this gen
     final TrackingDirectoryWrapper trackingDir = new TrackingDirectoryWrapper(dir);
     infosFormat.write(trackingDir, info.info, segmentSuffix, fieldInfos, infosContext);

lucene/core/src/java/org/apache/lucene/index/SortingTermVectorsConsumer.java

@@ -86,7 +86,7 @@ void flush(
   @Override
   void initTermVectorsWriter() throws IOException {
     if (writer == null) {
-      IOContext context = new IOContext(new FlushInfo(lastDocID, bytesUsed.get()));
+      IOContext context = IOContext.flush(new FlushInfo(lastDocID, bytesUsed.get()));
       tmpDirectory = new TrackingTmpOutputDirectoryWrapper(directory);
       writer = TEMP_TERM_VECTORS_FORMAT.vectorsWriter(tmpDirectory, info, context);
       lastDocID = 0;

lucene/core/src/java/org/apache/lucene/index/TermVectorsConsumer.java

@@ -102,7 +102,7 @@ void fill(int docID) throws IOException {
 
   void initTermVectorsWriter() throws IOException {
     if (writer == null) {
-      IOContext context = new IOContext(new FlushInfo(lastDocID, bytesUsed.get()));
+      IOContext context = IOContext.flush(new FlushInfo(lastDocID, bytesUsed.get()));
       writer = codec.termVectorsFormat().vectorsWriter(directory, info, context);
       lastDocID = 0;
       accountable = writer;

lucene/core/src/java/org/apache/lucene/store/DataAccessHint.java

@@ -0,0 +1,25 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.lucene.store;
+
+/** Hint on the data access pattern likely to be used */
+public enum DataAccessHint implements IOContext.FileOpenHint {
+  /** The access pattern is completely random */
+  RANDOM,
+  /** The access pattern is only sequential (forwards-only) */
+  SEQUENTIAL
+}

lucene/core/src/java/org/apache/lucene/store/DefaultIOContext.java

@@ -0,0 +1,83 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.lucene.store;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+record DefaultIOContext(Optional<ReadAdvice> readAdvice, Set<FileOpenHint> hints)
+    implements IOContext {
+
+  public DefaultIOContext {
+    Objects.requireNonNull(readAdvice);
+    Objects.requireNonNull(hints);
+    if (readAdvice.isPresent() && !hints.isEmpty())
+      throw new IllegalArgumentException("Either ReadAdvice or hints can be specified, not both");
+
+    // there should only be one hint of each type in the IOContext
+    Map<Class<? extends FileOpenHint>, List<FileOpenHint>> hintClasses =
+        hints.stream().collect(Collectors.groupingBy(IOContext.FileOpenHint::getClass));
+    for (var hintType : hintClasses.entrySet()) {
+      if (hintType.getValue().size() > 1) {
+        throw new IllegalArgumentException("Multiple hints of type " + hintType + " specified");
+      }
+    }
+  }
+
+  public DefaultIOContext(Optional<ReadAdvice> readAdvice, FileOpenHint... hints) {
+    this(readAdvice, Set.of(hints));
+  }
+
+  @Override
+  public Context context() {
+    return Context.DEFAULT;
+  }
+
+  @Override
+  public MergeInfo mergeInfo() {
+    return null;
+  }
+
+  @Override
+  public FlushInfo flushInfo() {
+    return null;
+  }
+
+  @Override
+  public IOContext withHints(FileOpenHint... hints) {
+    if (readAdvice().isPresent())
+      throw new IllegalArgumentException("ReadAdvice has been specified directly");
+    // TODO: see if this is needed or not
+    if (!hints().isEmpty()) throw new IllegalArgumentException("Hints have already been specified");
+    return new DefaultIOContext(Optional.empty(), hints);
+  }
+
+  private static final DefaultIOContext[] READADVICE_TO_IOCONTEXT =
+      Arrays.stream(ReadAdvice.values())
+          .map(r -> new DefaultIOContext(Optional.of(r)))
+          .toArray(DefaultIOContext[]::new);
+
+  @Override
+  public DefaultIOContext withReadAdvice(ReadAdvice advice) {
+    return READADVICE_TO_IOCONTEXT[advice.ordinal()];
+  }
+}

lucene/core/src/java/org/apache/lucene/store/FileDataHint.java

@@ -0,0 +1,27 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.lucene.store;
+
+/** Hints on the type of data stored in the file */
+public enum FileDataHint implements IOContext.FileOpenHint {
+  /** The file contains postings data */
+  POSTINGS,
+  /** The file contains stored fields */
+  STORED_FIELDS,
+  /** The file contains vector data for kNN search */
+  KNN_VECTORS
+}

lucene/core/src/java/org/apache/lucene/store/FileTypeHint.java

@@ -0,0 +1,27 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.lucene.store;
+
+/** Hints on the type of file being opened */
+public enum FileTypeHint implements IOContext.FileOpenHint {
+  /** The file contains metadata */
+  METADATA,
+  /** The file contains field data */
+  DATA,
+  /** The file contains indexes */
+  INDEX
+}