How To Make Entries Dependent On The Clients Lifetime

<< Back to the .Networking page

Ordinarily, keys stored on the Shared Dictionary server persist indefinitely and independent of any instance connection. However, the SD specifies two highly useful reserved key names: '.transient' and '.lifetime'. Both are used to control the lifetime of sub-trees in the Shared Dictionary hierarchy:

• The '.transient' key makes data persist only for the lifetime of the connected client. Its value is loaded with the user's GUID representing the client. When that client is disconnected, the key one level up from the .transient key plus all its children (including the .transient key) are deleted.
• The '.lifetime' key allows a developer to force data to persist for a specified time duration. Its value is loaded with a time value (in seconds). The shared dictionary server (not the clients) tracks this time from when the value is set, and will remove its parent and all its children when the specified duration has passed.

Excerpt from the Technical Report "Collabrary Shared Dictionary v1.0.17 - Programming Paradigm and Wire Protocol" by Mike Boyle:

Metadata
Specially constructed keys in the Collabrary Shared Dictionary are used to instruct the shared dictionary server to perform additional processing. These keys are called metadata keys. At present, there are three kinds of metadata:

.transient keys
This kind of metadata keys make it possible to bind the existence of keys to the presence of a particular client connected to the shared dictionary. In particular, the server will automatically remove sub-trees when the associated client disconnects, be it abortively or gracefully. When a client is disconnected from the shared dictionary, all remaining connected shared dictionary instances search their caches for items with keys that match the pattern /*/.transient and have string values that exactly match the instance GUID of the client that disconnected. When such an item is found, the sequence /../+ is appended to the key and the resulting pattern is used to remove items from the shared dictionary. Let’s suppose that the client with instanced GUID {guid} has disconnected from the shared dictionary, and there is a key /users/mike/.transient in the shared dictionary with value equal to {guid}. The shared dictionary will automatically remove any key that matches the pattern /users/mike/.transient/../+ -> /users/mike+, i.e., the entire sub-tree rooted at /users/mike.

.timestamp keys
The .timestamp key holds the local machine’s date/time at which the associated key was added or last changed. This kind of metadata key never passes from client to server or back. Instead, each client maintains this metadata itself. You cannot set this key’s value; you can only query it. Subscriptions on these keys are never evaluated. For example, if you query for the /foo/.timestamp key, you will get back the date/time at which /foo/.timestamp/.. -> /foo was last changed/added. The date/time is always expressed relative to the local computer’s clock. As a result, two clients querying the same .lifetime key are likely to retrieve two different values.

.lifetime keys
This kind of metadata is used by the server to implement fixed lifetime keys. It stores the number of seconds from the time the .lifetime key is added or changed to the time when the server should automatically remove the corresponding sub-tree. For example, consider that a client sets /foo/.lifetime to 60. Sixty seconds (one minute) after the server processes this modification, it will remove /foo/.lifetime/../+ -> /foo+ (the entire sub-tree rooted at /foo) from the shared dictionary.