launchdarkly · abelonogov-ld · Sep 4, 2026 · Sep 15, 2026 · Sep 15, 2026 · Sep 15, 2026
@@ -26,6 +26,7 @@
 import org.junit.Test;
 
 import java.io.IOException;
+import java.util.concurrent.TimeUnit;
 
 import okhttp3.HttpUrl;
 import okhttp3.mockwebserver.MockResponse;
@@ -95,6 +96,36 @@ public void testTrackData() throws IOException, InterruptedException {
         }
     }
 
+    @Test
+    public void flushAndWaitReportsDelivery() throws IOException, InterruptedException {
+        try (MockWebServer mockEventsServer = new MockWebServer()) {
+            mockEventsServer.start();
+            mockEventsServer.enqueue(new MockResponse());
+
+            LDConfig ldConfig = baseConfigBuilder(mockEventsServer).build();
+            try (LDClient client = LDClient.init(application, ldConfig, ldContext, 0)) {
+                client.track("test-event");
+
+                assertTrue(client.flushAndWait(5, TimeUnit.SECONDS));
+                LDValue[] events = getEventsFromLastRequest(mockEventsServer, 2);
+                assertCustomEvent(events[1], ldContext, "test-event");
+            }
+        }
+    }
+
+    @Test
+    public void flushAndWaitReportsFailureOnceClosed() throws IOException {
+        try (MockWebServer mockEventsServer = new MockWebServer()) {
+            mockEventsServer.start();
+
+            LDConfig ldConfig = baseConfigBuilder(mockEventsServer).build();
+            LDClient client = LDClient.init(application, ldConfig, ldContext, 0);
+            client.close();
+
+            assertFalse(client.flushAndWait(5, TimeUnit.SECONDS));
+        }
+    }
+
     @Test
     public void testTrackDataValueNull() throws IOException, InterruptedException {
         try (MockWebServer mockEventsServer = new MockWebServer()) {

@@ -25,6 +25,7 @@
 
 import java.util.HashMap;
 import java.util.Map;
+import java.util.concurrent.Future;
 
 /**
  * This class contains the package-private implementations of component factories and builders whose
@@ -72,6 +73,12 @@ public void flush() {}
         @Override
         public void blockingFlush() {}
 
+        @Override
+        public Future<Boolean> flushAsync() {
+            // Nothing was recorded, so there is nothing undelivered to warn the caller about.
+            return new LDSuccessFuture<>(true);
+        }
+
         @Override
         public void setInBackground(boolean inBackground) {}
 

@@ -133,6 +133,19 @@ final class DirectEventProcessor implements EventProcessor {
     /** Set under {@link #submitLock} once close() has queued the release of the sender. */
     private boolean shuttingDown = false;
 
+    /**
+     * Guards {@link #pendingFlush}. Taken on a caller's thread and on the delivery thread, never
+     * while holding {@link #recordLock}, and nothing blocking happens under it.
+     */
+    private final Object flushLock = new Object();
+
+    /**
+     * The delivery that is queued but has not started, which a flush request arriving now can wait
+     * on instead of queueing another. Null while nothing is queued, and cleared again as the queued
+     * delivery begins, which is the point past which it can no longer speak for what is recorded.
+     */
+    private LDAwaitFuture<Boolean> pendingFlush;
+
     DirectEventProcessor(
             OutboundEventBuffer buffer,
             EventSender eventSender,
@@ -331,21 +344,12 @@ public void setOffline(boolean offline) {
 
     @Override
     public void flush() {
-        if (isStopped()) {
-            return;
-        }
-        submit(this::deliverPayload);
+        flushAsync();
     }
 
     @Override
     public void blockingFlush() {
-        if (isStopped()) {
-            return;
-        }
-        Future<?> delivery = submit(this::deliverPayload);
-        if (delivery == null) {
-            return;
-        }
+        Future<Boolean> delivery = flushAsync();
         try {
             delivery.get();
         } catch (InterruptedException e) {
@@ -355,6 +359,61 @@ public void blockingFlush() {
         }
     }
 
+    @Override
+    public Future<Boolean> flushAsync() {
+        if (isStopped()) {
+            return new LDSuccessFuture<>(false);
+        }
+        return queueDelivery();
+    }
+
+    /**
+     * Queues a delivery, or hands back one that is already queued and has not started.
+     * <p>
+     * A delivery that has not started yet will take everything recorded up to the moment it does,
+     * which includes whatever the caller recorded before asking, so waiting on it answers the
+     * caller's question as well as a delivery of its own would. Without this, flushes arriving
+     * faster than a post completes each queue their own, and the one that matters -- the
+     * {@code flushAndWait} at shutdown -- waits behind all of them.
+     */
+    private Future<Boolean> queueDelivery() {
+        synchronized (flushLock) {
+            if (pendingFlush != null) {
+                return pendingFlush;
+            }
+            LDAwaitFuture<Boolean> result = new LDAwaitFuture<>();
+            if (submit(() -> runDelivery(result)) == null) {
+                // Shutting down, so there is no thread left to deliver on and nothing will be sent.
+                return new LDSuccessFuture<>(false);
+            }
+            pendingFlush = result;
+            return result;
+        }
+    }
+
+    /**
+     * Runs one delivery on behalf of every flush request that joined it, and tells them all how it
+     * went.
+     */
+    private void runDelivery(LDAwaitFuture<Boolean> result) {
+        synchronized (flushLock) {
+            // Requests arriving from here on need a delivery of their own: this one is about to take
+            // the buffer, and what it takes is all it can speak for.
+            if (pendingFlush == result) {
+                pendingFlush = null;
+            }
+        }
+        boolean delivered = false;
+        try {
+            delivered = deliverPayloadReportingOutcome();
+        } catch (Throwable t) {
+            // Caught here rather than left to guarded(), because a caller is waiting on the future
+            // and completing it matters more than the stack reaching the executor.
+            logUnexpectedError(t);
+        }
+        result.set(delivered);
+    }
+
     @Override
     public void close() throws IOException {
         if (!closed.compareAndSet(false, true)) {
@@ -368,22 +427,23 @@ public void close() throws IOException {
         // once the processor is gone. While offline that chance is not taken, and whatever is held
         // is discarded. Offline is the application telling the SDK to stay off the network, and
         // shutting down does not revoke that.
-        Future<?> delivery = submit(this::deliverPayload);
-        if (delivery != null) {
-            try {
-                delivery.get(closeBudgetMillis, TimeUnit.MILLISECONDS);
-            } catch (TimeoutException e) {
-                // Deliberately not cancelled. The run has already been drained into a payload, so
-                // interrupting now would make the loss certain, while leaving it to run costs
-                // nothing: the scheduler thread is a daemon, and returning from close() does not
-                // end an Android process. The budget bounds the caller, not the delivery.
-                logger.warn("Gave up waiting for the final event delivery after {}ms;" +
-                        " it continues in the background", closeBudgetMillis);
-            } catch (InterruptedException e) {
-                Thread.currentThread().interrupt();
-            } catch (ExecutionException e) {
-                logUnexpectedError(e.getCause() == null ? e : e.getCause());
-            }
+        //
+        // Queued directly rather than through flushAsync(), which refuses once closed is set, but
+        // through the same coalescing: a delivery that has not started yet will take these events
+        // too, so there is no reason to queue a second one behind it.
+        try {
+            queueDelivery().get(closeBudgetMillis, TimeUnit.MILLISECONDS);
+        } catch (TimeoutException e) {
+            // Deliberately not cancelled. The run has already been drained into a payload, so
+            // interrupting now would make the loss certain, while leaving it to run costs
+            // nothing: the scheduler thread is a daemon, and returning from close() does not
+            // end an Android process. The budget bounds the caller, not the delivery.
+            logger.warn("Gave up waiting for the final event delivery after {}ms;" +
+                    " it continues in the background", closeBudgetMillis);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        } catch (ExecutionException e) {
+            logUnexpectedError(e.getCause() == null ? e : e.getCause());
         }
         // Queued on both of the threads that post through the sender, so that it is released by
         // whichever of them finishes last. Closing it here instead would pull the HTTP client out
@@ -425,17 +485,29 @@ private void releaseSenderWhenLast() {
     }
 
     /**
-     * Serializes and sends everything buffered. Runs on the scheduler thread, which is
-     * single-threaded, so only one payload is ever in flight and the run is taken exactly once per
-     * delivery.
-     * <p>
-     * The run and the counters are taken together under {@link #recordLock}, so an evaluation is
-     * never split across two payloads, and encoded outside it, so recording does not wait on the
-     * encoder.
+     * Serializes and sends everything buffered, for the periodic flush, which has nobody waiting to
+     * find out how it went. It is a fixed-delay series, so a run is only ever scheduled once the one
+     * before it has finished and these cannot pile up the way requested flushes could.
      */
     private void deliverPayload() {
+        deliverPayloadReportingOutcome();
+    }
+
+    /**
+     * Delivers as {@link #deliverPayload()} does, and says whether it worked, for the callers of a
+     * requested flush, who are waiting to find out.
+     * <p>
+     * Runs on the scheduler thread, which is single-threaded, so only one payload is ever in flight
+     * and the run is taken exactly once per delivery. The run and the counters are taken together
+     * under {@link #recordLock}, so an evaluation is never split across two payloads, and encoded
+     * outside it, so recording does not wait on the encoder.
+     *
+     * @return true if the events reached the service, or if there were none to send; false if they
+     *   could not be sent or the service did not accept them
+     */
+    private boolean deliverPayloadReportingOutcome() {
         if (disabled || offline.get()) {
-            return;
+            return false;
         }
         List<Event> run;
         List<EventSummarizer.EventSummary> summaries;
@@ -450,19 +522,22 @@ private void deliverPayload() {
             payload = buffer.encode(run, summaries);
         } catch (IOException e) {
             logUnexpectedError(e);
-            return;
+            return false;
         }
         if (payload == null) {
-            return;
+            return true;
         }
         if (diagnosticStore != null) {
             diagnosticStore.recordEventsInBatch(payload.getEventCount());
         }
         try {
-            handleResponse(eventSender.sendAnalyticsEvents(payload.getData(),
-                    payload.getEventCount(), eventsUri));
+            EventSender.Result result = eventSender.sendAnalyticsEvents(payload.getData(),
+                    payload.getEventCount(), eventsUri);
+            handleResponse(result);
+            return result != null && result.isSuccess();
         } catch (Exception e) {
             logUnexpectedError(e);
+            return false;
         }
     }
 

@@ -779,6 +779,49 @@ private void flushInternal() {
         eventProcessor.flush();
     }
 
+    @Override
+    public boolean flushAndWait(long timeout, TimeUnit unit) {
+        long deadline = System.nanoTime() + unit.toNanos(timeout);
+        Map<String, LDClient> clients = getInstancesIfTheyIncludeThisClient();
+        if (clients.isEmpty()) {
+            // This client has been closed, or replaced by a later init; either way it can deliver
+            // nothing, and saying otherwise would tell the caller its events were safe.
+            return false;
+        }
+        // Every environment is started before any of them is waited on. Each has its own event
+        // processor and its own thread, so waiting on one before starting the next would spend the
+        // caller's budget on deliveries that could have been running all along.
+        List<Future<Boolean>> deliveries = new ArrayList<>(clients.size());
+        for (LDClient client : clients.values()) {
+            deliveries.add(client.eventProcessor.flushAsync());
+        }
+        boolean delivered = true;
+        for (Future<Boolean> delivery : deliveries) {
+            // Each wait gets what is left of the one budget rather than a fresh copy of it, so that
+            // the timeout the caller asked for is the time this call can take.
+            delivered &= awaitDelivery(delivery, Math.max(0, deadline - System.nanoTime()));
+        }
+        return delivered;
+    }
+
+    private boolean awaitDelivery(Future<Boolean> delivery, long remainingNanos) {
+        try {
+            return Boolean.TRUE.equals(delivery.get(remainingNanos, TimeUnit.NANOSECONDS));
+        } catch (TimeoutException e) {
+            // Left running rather than cancelled: the events have been taken out of the buffer by
+            // now, so interrupting the delivery would only make losing them certain.
+            return false;
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            return false;
+        } catch (ExecutionException e) {
+            Throwable cause = e.getCause() == null ? e : e.getCause();
+            logger.error("Exception caught when flushing events: {}", LogValues.exceptionSummary(cause));
+            logger.debug("{}", LogValues.exceptionTrace(cause));
+            return false;
+        }
+    }
+
     @VisibleForTesting
     void blockingFlush() {
         eventProcessor.blockingFlush();

@@ -11,6 +11,7 @@
 import java.io.Closeable;
 import java.util.Map;
 import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
 
 /**
  * The interface for the LaunchDarkly SDK client.
@@ -146,6 +147,27 @@ public interface LDClientInterface extends Closeable {
      */
     void flush();
 
+    /**
+     * Sends all pending events to LaunchDarkly and waits for them to be delivered.
+     * <p>
+     * Unlike {@link #flush()}, which returns before the events reach the network, this reports
+     * whether they arrived, which is what makes it usable at a point where the application is about
+     * to lose the ability to send them: an uncaught exception handler, a move to the background, or
+     * any other last chance. Events buffered in memory do not survive the process, so a caller that
+     * knows the process is ending can use this to give them one.
+     * <p>
+     * The timeout bounds the whole call, including when the SDK is configured for more than one
+     * environment. Choose it with the caller in mind: a dying process is not a good place to wait on
+     * a network request that may never answer.
+     *
+     * @param timeout how long to wait for delivery
+     * @param unit the time unit of {@code timeout}
+     * @return true if the events were delivered, or there were none to deliver; false if the timeout
+     *   expired first, or the SDK is offline, closed, or otherwise unable to deliver them
+     * @since 5.17.0
+     */
+    boolean flushAndWait(long timeout, TimeUnit unit);
+
     /**
      * Returns a map of all feature flags for the current evaluation context. No events are sent to LaunchDarkly.
      *

@@ -4,6 +4,7 @@
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.concurrent.Callable;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
@@ -83,6 +84,28 @@ public static <T> LDAwaitFuture<T> fromFuture(Future<T> future) {
         return result;
     }
 
+    /**
+     * Runs a blocking call on a pooled daemon thread and reports its result as a future.
+     * <p>
+     * Use this where a caller has a deadline but the work it is waiting for has no way to take one.
+     * The call is left running if the caller stops waiting; nothing interrupts it.
+     *
+     * @param task the blocking call
+     * @param <T>  result type
+     * @return a future that completes with the call's result, or with whatever it threw
+     */
+    public static <T> Future<T> fromBlockingCall(Callable<T> task) {
+        LDAwaitFuture<T> result = new LDAwaitFuture<>();
+        getBridgeExecutor().execute(() -> {
+            try {
+                result.set(task.call());
+            } catch (Throwable t) {
+                result.setException(t);
+            }
+        });
+        return result;
+    }
+
     /**
      * Returns a future that completes when the first of the given futures completes.
      * Equivalent to CompletableFuture.anyOf. Works with any {@link Future} (API-level safe).