Document failure behaviour for register ops (#132173)

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.

Author: DaveCTurner

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