Class: SharedStore

SharedStore

abstractnew SharedStore(args)

src/shared_store.js, line 32

Share a data store between users

Stores data in a location shared between several users. Most bulletin board software doesn't provide a mechanism to lock a resource when writing. To prevent race conditions where two users overwrite each other's updates, we call out to a third-party locking service. See /lock.rb in this repository for an example implementation. Note: if this string is empty, the object will work but will not protect against race conditions
Name Type Description
args Object store arguments
Example
var shared_store = new SharedStore({
    lock_url: 'http://.../...', // third-party URL to lock the store during writing
    store   : function(data) {...}, // called when we want to store a new string
    retrieve: function() {...}, // called when we want to download a string
    error_callback: function(message, resolutions),
    v: v
});

Methods

change(callback, retrieval)

src/shared_store.js, line 108

Add a callback for when the value changes, or fire a change event

Name Type Description
callback function optional
retrieval jQuery.Promise optional callback
Example
ss.change(function(data) { console.log(data) }); // no return value
ss.change().then(function(data) {...}); // also calls previous change_cbs

The store is checked at regular intervals, and will be called whenever
the value changes.

interval_transaction(updater)

src/shared_store.js, line 146

transaction handlers called regularly

Sometimes we need to write to the store regularly, and it's more efficient to do one big write instead of several small ones.
Name Type Description
updater function callback
Example
ss.interval_transaction(function(data) {
    data.last_active_time = new Date().getTime(); // see the 'offset' value in BulletinBoard.ping()
    return true; // data has changed, should do a write
});

transaction(updater){jQuery.Promise}

src/shared_store.js, line 170

update the value

To ensure users can't overwrite each other's changes, we lock the store, retrieve and update the value, then store it again. Change callbacks might be called after the retrieve(), but will not be called when the update goes through.
Name Type Description
updater function called to update the value
Returns:
Type Description
jQuery.Promise promise that succeeds when the change goes through
Example
ss.transaction(function(data) {
    ++data.value; // update the value
    return true; // signal that an update is needed
}).then(function(new_data) {
    console.log( "new data" );
});

val(){Object}

src/shared_store.js, line 86

get the stored value

because this value is stored remotely, this just returns the cached value. See transaction() and change()
Returns:
Type Description
Object stored value