Persistent Namespaces are used to allow one event to save data that can be used subsequently by another event.
A Namespace is a collection of variables and their values. When The Enforcer runs a notecard in response to an event, it creates a temporary namespace for that execution. This means that every event occurrence gets its own set of variables. In order to retain data, so that another event could use it later, the data has to be put into a Persistent Namespace.
A Persistent Namespace is a collection of variables, just like a regular namespace, but the variables in a Persistent Namespace cannot be accessed directly by a program running for an event. Instead, the program obtains a copy of the variable that it's interested in, in its own namespace, manipulates the local copy, and then puts the updated value back into the Persistent Namespace.
Before accessing a Persistent Namespace, the namespace must be created. This can be done manually, from The Enforcer's menu, or from within a program script, via the !namespace command:
Syntax:
!namespace <namespace-name>
Example:
!namespace Shared
Description:
If the specified namespace does not already exist, it will be created. If the namespace exists, the command is a no-op.
Once the namespace, called "Shared" in the example, is created, then a variable within the namespace can be associated with a new variable of the same name in the local namespace, via the !attach command:
Syntax:
!attach <namespace-name>::<variable-name>
Example:
!attach Shared::x
Description:
Copies the value of the specified variable in the specified Persistent Namespace into a new variable of the same name in the local namespace. If the variable does not exist in the Persistent Namespace, it will be treated as an empty string.
The variable in the Persistent Namespace is linked to the local namespace so that attempts to attach to it from a different local namespace will be held up until the current program either terminates, or uses the !detach command to detach from the Persistent Namespace.
Once a program has attached to a variable in a Persistent Namespace, it can manipulate the local copy of that variable using regular commands. When it wishes to update the variable in the Persistent Namespace, it does so with the !detach command:
Syntax:
!detach <namespace-name>::<variable-name>
Example:
!detach Shared::x
Description:
Copies the value of the specified variable in the local namespace back into the Persistent Namespace. The variable must have previously been attached to the local namespace. After !detach completes, the variable is no longer attached (and if other programs are waiting to attach to it, one of them will be allowed to continue).
When a program terminates and its namespace is deleted, any Persistent Namespace variables that were attached will be detached automatically; however, their values will not be updated from the local versions.
If a program merely wants to read the current value of a variable in a Persistent Namespace, and does not want to be able to change the value, it can use the !get command. Like !attach, !get will copy the value of a variable in a Persistent Namespace into a local variable, but it will not create any link between the Persistent variable and the local variable.
Syntax:
!get <namespace-name>::<variable-name>
Example:
!get Shared::x
Description:
Copies the value of the specified variable in the specified Persistent Namespace into a new variable of the same name in the local namespace. If the variable does not exist in the Persistent Namespace, it will be treated as an empty string. After !get completes, no association is maintained between the variable in the Persistent Namespace and the local copy.
No comments:
Post a Comment