RetainedValuesStore
-
Cmn
interface RetainedValuesStore
ForgetfulRetainedValuesStore |
The |
ManagedRetainedValuesStore |
A |
A RetainedValuesStore acts as a storage area for objects being retained. When a retained value is in the composition, then the composition hierarchy owns the value and retains it there. RetainedValuesStore defines what happens to a retained value when it leaves and re-enters the compositions.
Retained objects are offered to implementations of RetainedValuesStore as they exit the composition. Implementations may continue to retained such exited objects until they are restored into the composition hierarchy when the removed content is recreated. Implementations define whether, how, and for how long retained values should be stored after they leave the composition.
The general pattern for retention is as follows:
-
The RetainedValuesStore receives a call to
onContentExitCompositionsignaling that the owned content is about to be removed. -
Transient content removal begins. The content is recomposed, removed from the hierarchy, and remembered values are forgotten. Values remembered by
retainleave the composition but are not yet released. Every value returned byretainwill be passed as an argument tosaveExitingValueso that it can later be returned by getExitedValueOrDefault. -
An arbitrary amount of time passes, and the store is installed in the composition hierarchy again along with its content. When a
retaincall is invoked during the restoration, it calls getExitedValueOrDefault. If all the input keys match a retained value, the previous result is returned and the retained value is removed from the pool of restorable objects that exited the previous composition. This step may be skipped if it becomes impossible to return to the transiently removed content while this store is retaining exited values. -
The content finishes composing after being restored, and the entire frame completes.
onContentEnteredCompositionis invoked to signal the complete consumption of all retained exited values. Any values that are retained and not currently used in a composition (and therefore not restored by getExitedValueOrDefault) are then immediately discarded.
A given RetainedValuesStore should only be used by a single Recomposer at a time. It can move between recomposers (for example, when the Window is recreated), but should never be used by two Recomposers simultaneously. Implementations may or may not support being used in multiple places simultaneously. Unless otherwise specified, it's assumed that an implementation of RetainedValuesStore should only be installed at one location in a single composition hierarchy.
Summary
Public functions |
||
|---|---|---|
Any? |
getExitedValueOrElse(key: Any, defaultValue: Any?)If this store is currently retaining exited values and has a value previously created with the given |
Cmn
|
Unit |
Invoked to indicate that all content has finished entering the composition for the first time after the store is installed. |
Cmn
|
Unit |
Invoked to indicate that the associated content is about to start leaving composition. |
Cmn
|
Unit |
saveExitingValue(key: Any, value: Any?)Invoked when a retained value is exiting composition while this store is retaining exited values. |
Cmn
|
Public functions
getExitedValueOrElse
fun getExitedValueOrElse(key: Any, defaultValue: Any?): Any?
If this store is currently retaining exited values and has a value previously created with the given key, its original record is returned and removed from the list of exited kept objects that this store is tracking.
This method is always called from the composition thread.
| Parameters | |
|---|---|
key: Any |
The keys to resolve a retained value that has left composition |
defaultValue: Any? |
A value to be returned if there are no retained values that have exited composition and are being held by this RetainedValuesStore for the given |
| Returns | |
|---|---|
Any? |
A retained value for |
onContentEnteredComposition
fun onContentEnteredComposition(): Unit
Invoked to indicate that all content has finished entering the composition for the first time after the store is installed. Any unconsumed retained values should be discarded at this time.
This function is called by the library when the store is installed with LocalRetainedValuesStoreProvider. It should not be invoked directly in production code. The default installation will always invoke this callback on the applier thread for the content's latest destination, which may differ when moved between compositions.
Implementors of this function MUST call RetainObserver.onRetired for all discarded values that implement RetainObserver following the threading guarantees specified in RetainObserver's documentation.
onContentExitComposition
fun onContentExitComposition(): Unit
Invoked to indicate that the associated content is about to start leaving composition. The store should make any necessary preparations to start retaining values as they exit the composition.
This function is called by the library when the store is installed with LocalRetainedValuesStoreProvider. It should not be invoked directly in production code. The default installation will always invoke this callback on the applier thread that content entered composition on.
saveExitingValue
fun saveExitingValue(key: Any, value: Any?): Unit
Invoked when a retained value is exiting composition while this store is retaining exited values. It is up to the implementation of this method to decide whether and how to store these values so that they can later be retrieved by getExitedValueOrElse.
The given key are not guaranteed to be unique. To handle duplicate keys, implementors should return retained values with the same keys from getExitedValueOrElse in the opposite order they are received by saveExitingValue.
If the implementation of this store does not accept this value into its kept exited object list, it MUST call RetainObserver.onRetired if value implements RetainObserver, following the threading guarantees specified in RetainObserver's documentation.
This method is always called from the applier thread.