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:
  • MergingFunctionAutomaticthe function applied to the list of values found
    ValuePreprocessingFunctionIdentitythe function applied to new values to be assigned
    ExpirationDateNonewhen the value should expire
    PersistenceTimeNonehow 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).

BibTeX

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

BibLaTeX

@online{reference.wolfram_2021_persistentvalue, organization={Wolfram Research}, title={PersistentValue}, year={2019}, url={https://reference.wolfram.com/language/ref/PersistentValue.html}, note=[Accessed: 18-June-2021 ]}

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