doc about non-blocking refreshes and reset

Author: tlrx

server/src/main/java/org/elasticsearch/index/engine/Engine.java

@@ -1289,7 +1289,7 @@ public void externalRefresh(String source, ActionListener<Engine.RefreshResult>
 
     /**
      * Asynchronously refreshes the engine for new search operations to reflect the latest
-     * changes unless another thread is already refreshing the engine concurrently.
+     * changes unless another thread is already refreshing or reseting the engine concurrently.
      */
     @Nullable
     public abstract void maybeRefresh(String source, ActionListener<RefreshResult> listener) throws EngineException;

server/src/main/java/org/elasticsearch/index/shard/IndexShard.java

@@ -4433,6 +4433,8 @@ public void afterRefresh(boolean didRefresh) {
      *
      * In general, resetting the engine should be done with care, to consider any in-progress operations and listeners.
      * At the moment, this is implemented in serverless for a special case that ensures the engine is prepared for reset.
+     * Reseting the engine can prevent non-blocking engine refreshes (see {@link Engine#maybeRefresh(String, ActionListener)} to be
+     * immediately executed, so it is expected that the new engine instance provides refreshed readers (if supported) after the reset.
      *
      * @param postResetNewEngineConsumer A consumer that will be called with the newly created engine after the reset
      *                                   is complete, allowing for post-reset operations on the new engine instance.