1 // Copyright 2023 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 package org.chromium.base.supplier; 6 7 import androidx.annotation.Nullable; 8 9 import org.chromium.base.Callback; 10 11 /** 12 * SyncOneshotSupplier wraps an asynchronously provided, non-null object {@code T}, synchronously 13 * notifying observers a single time when the dependency becomes available. Note that null is the 14 * sentinel value; a fulfilled supplier will never have a null value. 15 * 16 * <p>See {@link OneshotSupplier} for more details on when this might be useful. The key distinction 17 * between the two interfaces is that the callbacks registered to {@link #onAvailable(Callback)} are 18 * called synchronously when the object becomes is available. This is critical in some applications 19 * where the value might be needed immediately and the {@link Callback} cannot be posted. However, 20 * generally prefer {@link OneshotSupplier} if either will work to avoid main thread congestion. 21 * 22 * <p>This class must only be accessed from a single thread. Unless a particular thread designation 23 * is given by the owner of the OneshotSupplier, clients should assume it must only be accessed on 24 * the UI thread. 25 * 26 * <p>If you want to create a supplier, see an implementation in {@link SyncOneshotSupplierImpl}. 27 * 28 * @param <T> The type of the wrapped object. 29 */ 30 public interface SyncOneshotSupplier<T> extends Supplier<T> { 31 /** 32 * Add a callback that's synchronously called when the object owned by this supplier is 33 * available. If the object is already available, the callback will be called immediately. 34 * 35 * @param callback The callback to be called. 36 * @return The value for this supplier if already available. Null otherwise. 37 */ 38 @Nullable onAvailable(Callback<T> callback)39 T onAvailable(Callback<T> callback); 40 } 41