From 9b45bfd4d8bba820416ffb4a9f54cb2480f9bc67 Mon Sep 17 00:00:00 2001
From: David Turner <david.turner@elastic.co>
Date: Wed, 30 Jul 2025 12:36:06 +0100
Subject: [PATCH] Document failure behaviour for register ops

A failure of a write to a register does not indicate that the write has
definitely completed - it may eventually succeed at some later point in
time.
---
 .../elasticsearch/common/blobstore/BlobContainer.java | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/server/src/main/java/org/elasticsearch/common/blobstore/BlobContainer.java b/server/src/main/java/org/elasticsearch/common/blobstore/BlobContainer.java
index 340123456435f..c20d9832daf0a 100644
--- a/server/src/main/java/org/elasticsearch/common/blobstore/BlobContainer.java
+++ b/server/src/main/java/org/elasticsearch/common/blobstore/BlobContainer.java
@@ -308,6 +308,9 @@ default void copyBlob(
      * <p>
      * This operation, together with {@link #compareAndSetRegister}, must have linearizable semantics: a collection of such operations must
      * act as if they operate serially, with each operation taking place at some instant in between its invocation and its completion.
+     * <p>
+     * If the listener completes exceptionally then the write operation should be considered as continuing to run and may therefore appear
+     * to occur at some later point in time.
      *
      * @param purpose  The purpose of the operation
      * @param key      key of the value to update
@@ -330,6 +333,9 @@ void compareAndExchangeRegister(
      * <p>
      * This operation, together with {@link #compareAndExchangeRegister}, must have linearizable semantics: a collection of such operations
      * must act as if they operate serially, with each operation taking place at some instant in between its invocation and its completion.
+     * <p>
+     * If the listener completes exceptionally then the write operation should be considered as continuing to run and may therefore appear
+     * to occur at some later point in time.
      *
      * @param purpose  The purpose of the operation
      * @param key      key of the value to update
@@ -361,7 +367,10 @@ default void compareAndSetRegister(
      * This operation has read-after-write consistency with respect to writes performed using {@link #compareAndExchangeRegister} and
      * {@link #compareAndSetRegister}, but does not guarantee full linearizability. In particular, a {@code getRegister} performed during
      * one of these write operations may return either the old or the new value, and a caller may therefore observe the old value
-     * <i>after</i> observing the new value, as long as both such read operations take place before the write operation completes.
+     * <i>after</i> observing the new value, as long as both such read operations take place before the success of the write operation.
+     * <p>
+     * Write operations which complete exceptionally may behave as if they continue to run, thus yielding old or new values for an extended
+     * period of time. If multiple writes fail then {@code getRegister} may return any of the written values.
      *
      * @param purpose The purpose of the operation
      * @param key      key of the value to get