DataStore
interface DataStore<T>
DataStore provides a safe and durable way to store small amounts of data, such as preferences
and application state. It does not support partial updates: if any field is modified, the whole
object will be serialized and persisted to disk. If you want partial updates, consider the Room
API (SQLite).
DataStore provides ACID guarantees. It is thread-safe, and non-blocking. In particular, it
addresses these design shortcomings of the SharedPreferences API:
- Synchronous API encourages StrictMode violations
- apply() and commit() have no mechanism of signalling errors
- apply() will block the UI thread on fsync()
- Not durable – it can returns state that is not yet persisted
- No consistency or transactional semantics
- Throws runtime exception on parsing errors
- Exposes mutable references to its internal state
Summary
| Public methods |
| abstract suspend T |
Updates the data transactionally in an atomic read-modify-write operation.
|
| Properties |
| abstract Flow<T> |
Provides efficient, cached (when possible) access to the latest durably persisted state.
|
Public methods
updateData
abstract suspend fun updateData(transform: suspend (t: T) -> T): T
Updates the data transactionally in an atomic read-modify-write operation. All operations
are serialized, and the transform itself is a coroutine so it can perform heavy work
such as RPCs.
The coroutine completes when the data has been persisted durably to disk (after which
data will reflect the update). If the transform or write to disk fails, the
transaction is aborted and an exception is thrown.
| Return |
| the snapshot returned by the transform |
|
| Exceptions |
IOException |
when an exception is encountered when writing data to disk |
Exception |
when thrown by the transform function |
Properties
data
abstract val data: Flow<T>
Provides efficient, cached (when possible) access to the latest durably persisted state.
The flow will always either emit a value or throw an exception encountered when attempting
to read from disk. If an exception is encountered, collecting again will attempt to read the
data again.
Do not layer a cache on top of this API: it will be be impossible to guarantee consistency.
Instead, use data.first() to access a single snapshot.
| Return |
| a flow representing the current state of the data |
|
| Exceptions |
IOException |
when an exception is encountered when reading data |
