Recommendation: GSI LSNS (v1)
Structured key-value pair naming scheme to categorize LSL linkset data pairs
The Global Scripting Institute (GSI) is an informal organization of Second Life® users that design and test standards for efficient, flexible, and readable scripts in Second Life. "Second Life®" and "Second Life Grid™" are trademarks of Linden Research, Inc., d/b/a Linden Lab. The Global Scripting Institute and its catalog are not affiliated with with or sponsored by Linden Research.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
The linkset_data Scoped Naming Scheme (LSNS) is a naming scheme for llLinksetData*/linkset_data pairs in Linden Scripting Language (LSL).
Native linkset data is a key-value datastore that is specific to a single linkset. LSNS extends this by enforcing a mandatory naming scheme that assigns linkset data pairs to a specific scope - "linkset-scope", "prim-scope", and "script-scope" - by optionally incorporating the prim UUID and script name in the linkset data pair name.
Additionally, LSNS extends this further by allowing the script to add any number of additional elements to the name, which facilitates hierarchical trees of linkset data pairs instead of a flat key-value store.
This naming scheme is primarily designed to allow for complex cross-vendor script interoperability in the same object without accidentally modifying data managed by other scripts.
When a script that supports LSNS writes to or reads from linkset data, it MAY use a linkset data pair name that does not contain any newline ("\n") characters. If so, these are "non-LSNS" pairs that are outside the scope of this recommendation. However, if the script does not do this, it MUST use the LSNS naming scheme. In other words, any pair that contains a newline ("\n") character MUST be an LPDS pair.
Linkset data pairs that use LSNS MUST be named using a list (the "pair name list") dumped to a string with newline ("\n") delineation.
LSNS pairs may be one of three scopes - linkset-scope, prim-scope, and script-scope.
A linkset-scope pair operates the same as writing raw linkset data, but using the LSNS naming scheme. That is, it can be accessed by any script in any prim in the entire linkset. Except when performing maintenance or cleanup, linkset-scope pairs MUST be written and read as follows:
llLinksetDataWrite(llDumpList2String(["", ""] + pair_name_list, "\n"), data)
string data = llLinksetDataRead(llDumpList2String(["", ""] + pair_name_list, "\n"))
A prim-scope pair is only accessible to scripts within the same prim. Prim-scope pairs must be maintained when the prim UUID changes due to re-rezzing (see "Prim UUID Maintenance" section below). Except when performing maintenance or cleanup, prim-scope pairs MUST be written and read as follows:
llLinksetDataWrite(llDumpList2String([llGetKey(), ""] + pair_name_list, "\n"), data)
string data = llLinksetDataRead(llDumpList2String([llGetKey(), ""] + pair_name_list, "\n"))
A script-scope pair is only accessible to the script that wrote it within the same prim. Script-scope pairs, like prim-scope pairs, must be maintained when the prim UUID changes due to re-rezzing (see "Prim UUID Maintenance" section below). Except when performing maintenance or cleanup, script-scope pairs MUST be written and read as follows:
llLinksetDataWrite(llDumpList2String([llGetKey(), llGetScriptName()] + pair_name_list, "\n"), data)
string data = llLinksetDataRead(llDumpList2String([llGetKey(), llGetScriptName()] + pair_name_list, "\n"))
In all of the above examples, pair_name_list MUST be a list of one or more values that do not contain any newline ("\n") characters.
LSNS pairs MUST NOT use the llLinksetData*Protected functions. These functions make it impossible for other scripts to selectively clean the datastore of disassociated keys (see section on "Periodic Cleanup" below).
If prim-scope or script-scope pairs are used, the LSNS script MUST perform prim UUID maintenance when the prim UUID changes due to re-rezzing or duplication. When this happens, the LSNS script MUST iterate through all keys using llLinksetDataFindKeys and move any pairs that are associated with the prim's previous UUID, which must be stored in script memory.
As objects are linked and unlinked and scripts added and removed, the LSNS datastore can fill up with pairs from prims and/or scripts that are no longer part of the linkset. If this happens, the linkset data datastore can run out of memory.
LSNS scripts SHOULD perform periodic cleanup on LSNS linkset data pairs by pruning pairs that are associated with a prim UUID that is no longer part of the same linkset. If the LSNS script is in the same prim as the pair, it SHOULD also prune pairs that are associated with a script that is no longer in the prim's inventory.
LSNS does not do this automatically by design. LSNS scripts MAY perform this action either automatically or at the user's request, depending on the data's tolerance for accidental loss.
Can I modify other prims'/scripts' LSNS pairs?
No. While LSNS does not enforce this in code, LSNS-aware scripts MUST NOT access pairs outside their designated scopes to be considered compliant with the LSNS recommendation.
Can I use the same pair name list in multiple scopes?
Yes. The same pair name list MAY be used in multiple scopes, and this will create multiple linkset data pairs.
LSNS does not enforce priority of one scope over the other. For example, a pair with the name list ["abc"] MAY be written to multiple scopes with potentially conflicting data. It is up to the implementation reading the values on whether or how to resolve these conflicts. LSNS only establishes the spaces for these individual scopes; it does not address naming conflicts between them.
What is the benefit of linkset-scope LSNS pairs over using plain "non-LSNS" linkset data names?
LSNS only provides the hierarchical naming scheme in this instance; if you don't need that, it may not be worth using. Note that "non-LSNS" and LSNS pairs can coexist in the same datastore as long as the "non-LSNS" pairs do not use any newline ("\n") characters in their names.
LSNS was authored by Nelson Jenkins on behalf of GSI.