InterProcessCoordinator
public interface InterProcessCoordinator
InterProcessCoordinator provides functionalities that support DataStore instances to coordinate the concurrent work running on multiple threads and multiple processes to guarantee its data consistency. Typically users should use default coordinators provided by the library, including createSingleProcessCoordinator for use cases where DataStore is only used in a single process, and createMultiProcessCoordinator for a DataStore that needs to be accessed in multiple processes.
Summary
Public methods |
|
|---|---|
abstract @NonNull Flow<Unit> |
A flow that emits a Unit when the data for the DataStore changes. |
abstract int |
Atomically get the current version. |
abstract int |
Atomically increment version and return the new version. |
abstract @NonNull T |
Get the exclusive lock shared by the coordinators from DataStore instances (even from different processes) to run a suspending code |
abstract @NonNull T |
Attempt to get the exclusive lock shared by the coordinators from DataStore instances (even from different processes) and run the code |
Public methods
getUpdateNotifications
abstract @NonNull Flow<Unit> getUpdateNotifications()
A flow that emits a Unit when the data for the DataStore changes. DataStore collects this flow to signal the action to invalidate cache and re-read data from disk.
getVersion
abstract int getVersion()
Atomically get the current version. DataStore instances for the same data use this method to access the shared version for its cached data and internal state. Notice concurrent access to the version should guarantee data consistency.
incrementAndGetVersion
abstract int incrementAndGetVersion()
Atomically increment version and return the new version. DataStore instances for the same data use this method to access the shared version for its cached data and internal state. Notice concurrent access to the version should guarantee data consistency.
Note that the number of calls to the incrementAndGetVersion is an internal implementation detail for DataStore and implementers of this API should not make any assumption based on the number of version increments.
lock
abstract @NonNull T <T extends Object> lock(@NonNull SuspendFunction0<@NonNull T> block)
Get the exclusive lock shared by the coordinators from DataStore instances (even from different processes) to run a suspending code block that returns type T. It guarantees one-at-a-time execution for all the block called with this method. If some other process or thread is holding the lock, it will wait until the lock is available.
tryLock
abstract @NonNull T <T extends Object> tryLock(
@NonNull SuspendFunction1<@NonNull Boolean, @NonNull T> block
)
Attempt to get the exclusive lock shared by the coordinators from DataStore instances (even from different processes) and run the code block regardless of the attempt result. Pass a boolean to block to indicate if the attempt succeeds. If the attempt fails, block will run immediately after the attempt, without waiting for the lock to become available.