ViewModelStoreProvider
public final class ViewModelStoreProvider
Manages a set of ViewModelStore instances scoped to a parent ViewModelStore.
This class allows the creation of "child" scopes that survive configuration changes (via the parent owner) but can be independently cleared when no longer needed.
Important: This class prevents a child ViewModel from being cleared while they are still in use (e.g., during exit animations). Consumers must call acquireToken to mark a child ViewModelStore as active and then call ReferenceToken.close to release the token when finished. Calling clearKey or clearAllKeys will only perform the actual cleanup once all of a store's tokens have been released.
Null owner: If store is EXPLICITLY null, this creates a root provider that runs independently. It manages its own state and will not be automatically cleared by configuration changes; you must manually call clearAllKeys to clean it up.
Summary
Nested types |
|---|
public fun interface ViewModelStoreProvider.ReferenceToken extends AutoCloseableRepresents an active hold on a specific |
Public constructors |
|---|
ViewModelStoreProvider(Constructs a |
ViewModelStoreProvider( |
Public methods |
|
|---|---|
final @NonNull ViewModelStoreProvider.ReferenceToken |
acquireToken(Object key)Increments the reference count for the |
final void |
Triggers a cleanup pass on all managed stores. |
final void |
Marks the |
final @NonNull ViewModelStore |
getOrCreate(Object key)Retrieves or creates a |
final @NonNull ViewModelStoreOwner |
getOrCreateOwner(Retrieves or creates a |
Public constructors
ViewModelStoreProvider
public ViewModelStoreProvider(
ViewModelStoreOwner owner,
@NonNull CreationExtras defaultCreationExtras,
@NonNull ViewModelProvider.Factory defaultFactory
)
Constructs a ViewModelStoreProvider bound to a parent ViewModelStoreOwner.
| Parameters | |
|---|---|
ViewModelStoreOwner owner |
The parent |
@NonNull CreationExtras defaultCreationExtras |
The default creation extras to use for child stores. Defaults to resolving from the |
@NonNull ViewModelProvider.Factory defaultFactory |
The default factory to use for child stores. Defaults to resolving from the |
ViewModelStoreProvider
public ViewModelStoreProvider(
ViewModelStore store,
@NonNull CreationExtras defaultCreationExtras,
@NonNull ViewModelProvider.Factory defaultFactory
)
| Parameters | |
|---|---|
ViewModelStore store |
The parent |
@NonNull CreationExtras defaultCreationExtras |
The default creation extras to use for child stores. |
@NonNull ViewModelProvider.Factory defaultFactory |
The default factory to use for child stores. |
Public methods
acquireToken
public final @NonNull ViewModelStoreProvider.ReferenceToken acquireToken(Object key)
Increments the reference count for the ViewModelStore associated with the given key, ensuring it is not cleared until the returned [] is released.
| Parameters | |
|---|---|
Object key |
The unique identifier for the child scope. |
| Returns | |
|---|---|
@NonNull ViewModelStoreProvider.ReferenceToken |
A token that must be released via |
clearAllKeys
public final void clearAllKeys()
Triggers a cleanup pass on all managed stores.
Any ViewModelStore that has a reference count of zero will have its ViewModelStore.clear method called and will be removed from the internal map. Stores with active references are marked as removable and will be deferred until their count reaches zero.
clearKey
public final void clearKey(Object key)
Marks the ViewModelStore associated with the given key as removable.
If the store currently has a reference count of zero, it is cleared immediately. Otherwise, the actual cleanup is deferred until all acquired tokens are released.
| Parameters | |
|---|---|
Object key |
The unique identifier for the child scope. |
getOrCreate
public final @NonNull ViewModelStore getOrCreate(Object key)
Retrieves or creates a ViewModelStore associated with the given key.
If a store with this key already exists, it is returned. If not, a new store is created. To protect this store from being prematurely cleared, you must call acquireToken.
| Parameters | |
|---|---|
Object key |
The unique identifier for the child scope. |
| Returns | |
|---|---|
@NonNull ViewModelStore |
The |
getOrCreateOwner
public final @NonNull ViewModelStoreOwner getOrCreateOwner(
Object key,
SavedStateRegistryOwner savedStateRegistryOwner,
@NonNull CreationExtras defaultCreationExtras,
@NonNull ViewModelProvider.Factory defaultFactory
)
Retrieves or creates a ViewModelStoreOwner associated with the given key.
This method creates a new lightweight wrapper around the ViewModelStore.
Important: This does not automatically increment the reference count. If you are holding onto this owner asynchronously or across recompositions, you should call acquireToken to protect its lifecycle.
Saved State Support: If a savedStateRegistryOwner is provided, the returned ViewModelStoreOwner will also implement SavedStateRegistryOwner, delegating state resolution to the provided owner. This is required if ViewModels within this scope depend on androidx.lifecycle.SavedStateHandle. When saved state is enabled and defaultFactory is not explicitly overridden, it automatically upgrades to a SavedStateViewModelFactory.
| Parameters | |
|---|---|
Object key |
The unique identifier for the child scope. |
SavedStateRegistryOwner savedStateRegistryOwner |
An optional parent registry owner to delegate saved state operations to. If |
@NonNull CreationExtras defaultCreationExtras |
An optional override for the default |
@NonNull ViewModelProvider.Factory defaultFactory |
An optional override for the default |
| Returns | |
|---|---|
@NonNull ViewModelStoreOwner |
A scoped |
| Throws | |
|---|---|
IllegalArgumentException |
If |