PersistentValue

As of Version 12.3, PersistentValue has been renamed PersistentSymbol.

PersistentValue["name"]

represents the persistent value associated with the key "name".

PersistentValue["name",loc]

represents the persistent value associated with name stored in persistence location loc.

PersistentValue["name",{loc1,…}]

represents the persistent value associated with name at the first of the locations loci at which it occurs.

Details and Options

  • PersistentValue["name",…] evaluates to give the corresponding persistent value.
  • PersistentValue["name",…]=value sets a persistent value.
  • PersistentValue allows the following options:
  • MergingFunction Automaticthe function applied to the list of values found
    ValuePreprocessingFunction Identitythe function applied to new values to be assigned
    ExpirationDate Nonewhen the value should expire
    PersistenceTime Nonehow long the value should persist
  • In PersistentValue["name",loc], possible forms for the persistence location loc include:
  • PersistenceLocation["type"]"Local", "Cloud", "FrontEndSession", etc. locations
    "type"equivalent to PersistenceLocation["type"]
    PersistenceLocation["type","base"]location with a particular base (directory etc.)
    "type""base"equivalent to PersistenceLocation["type","base"]
  • Supported location types include:
  • "KernelSession"current invocation of the Wolfram Language kernel
    "FrontEndSession"current invocation of the Wolfram Notebook front end
    "Notebook"the notebook in which the current evaluation is being done
    "ServerSession"persistence for requests on a single web server
    "CookieManaged"persistence based on a Wolfram browser cookie
    "Local"local to a computer, based on user home directory
    "LocalShared"local to a computer, based on $BaseDirectory
    "Cloud"in the cloud defined by the current $CloudBase
    "Installation"installation defaults
  • PersistentValue["name"] is equivalent to PersistentValue["name",$PersistencePath].
  • PersistentValue["name"]=value is equivalent to PersistentValue["name",$PersistenceBase]=value.
  • PersistentValue["name",loc] is essentially PersistentObject["name",loc]["Value"].
  • When a single persistence location is specified, as in PersistentValue["name",loc,…], the setting for MergingFunction is not used.
  • Otherwise, with the setting MergingFunction->f, the final value returned is the result of applying the function f to the list of values found at all persistence locations.
  • Unless specified otherwise by "MergingFunction" metadata in the PersistentObject, MergingFunction->Automatic is equivalent to MergingFunction->First.
  • Before a new value is assigned in PersistentValue[sym]=value, any specified value preprocessing function is applied to value before the value is assigned.
  • If the preprocessing function returns $Failed, the assignment is not performed.
  • If no explicit setting for ValuePreprocessingFunction is given, the setting to use is looked up on $PersistencePath.
  • An expired persistent value is treated as nonexistent, and the underlying persistent object may be removed.
  • Persistent values can be removed with Remove. Remove[PersistentValue["name"]] is equivalent to Remove[PersistentValue["name",$PersistenceBase]].

Examples

open allclose all

Basic Examples  (3)

Assign a persistent value:

Retrieve a previously saved value:

Remember a value with front end session scope:

Use the saved value, even in a newly restarted kernel within the same front end session:

Store values for the same name at different persistence locations:

Retrieve the first value found:

Retrieve the list of all values on $PersistencePath:

Options  (8)

MergingFunction  (3)

Create a complement of persistent values with key "lval" at various locations:

List all existing values for the key "lval" on $PersistencePath:

By default, only the first value is returned:

Join and flatten all sublists:

Join all sublists:

Create a complement of persistent associations with name "aval" at various locations:

List all existing values on $PersistencePath:

Merge the values of identical keys in the associations:

Define a default value for "mylist" with a custom merging function:

Define additional values at different persistence locations:

For looking up values, the custom merging function is now used:

PersistenceTime  (2)

Define a persistent value that expires in 5 seconds:

After 5 seconds, it is no longer used:

Define a persistent object that expires in 5 days:

Verify the expiration date of the underlying persistent object:

ExpirationDate  (2)

Define a persistent value that expires at the beginning of the year 2020:

Verify the expiration date of the underlying persistent object:

Define a persistent value that expires at the beginning of next year:

Verify the expiration date of the underlying persistent object:

ValuePreprocessingFunction  (1)

Define a value preprocessing function for a particular persistent value that accepts only integers:

Assign an integer at any persistence location:

Assigning anything else generates an error and the assignment is not performed:

Applications  (1)

List all existing persistent objects for the key "lval":

Delete them:

Properties & Relations  (5)

Persistent values are stored in persistent objects:

The default location of a new persistent object is given by $PersistenceBase:

Create a complement of persistent values with key "v" at various locations:

Persistent values are by default searched on all locations given in $PersistencePath:

The first value found is returned:

With MergingFunction->Identity, all values found are returned in a list:

Specify an explicit list of locations to search for values:

Expiration times specified with PersistenceTime are converted to absolute expiration dates:

Persistent values can be removed with Remove:

Possible Issues  (1)

Create two persistent values for "name" in different locations:

Remove by default removes only the value in the location given by $PersistenceBase:

Remove all values that might exist anywhere in the locations given by $PersistencePath:

Wolfram Research (2017), PersistentValue, Wolfram Language function, https://reference.wolfram.com/language/ref/PersistentValue.html (updated 2019).

Text

Wolfram Research (2017), PersistentValue, Wolfram Language function, https://reference.wolfram.com/language/ref/PersistentValue.html (updated 2019).

CMS

Wolfram Language. 2017. "PersistentValue." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2019. https://reference.wolfram.com/language/ref/PersistentValue.html.

APA

Wolfram Language. (2017). PersistentValue. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/PersistentValue.html

BibTeX

@misc{reference.wolfram_2023_persistentvalue, author="Wolfram Research", title="{PersistentValue}", year="2019", howpublished="\url{https://reference.wolfram.com/language/ref/PersistentValue.html}", note=[Accessed: 19-April-2024 ]}

BibLaTeX

@online{reference.wolfram_2023_persistentvalue, organization={Wolfram Research}, title={PersistentValue}, year={2019}, url={https://reference.wolfram.com/language/ref/PersistentValue.html}, note=[Accessed: 19-April-2024 ]}