biomedjs/node_modules/strong-store-cluster/README.md

# Strong Store Cluster

Strong Store for Cluster provides a key/value collection that can be accesses by
all processes in a node cluster.

## Example

```javascript
// get the collection and give it a name
var collection = require('strong-store-cluster').collection('test');

// don't let keys expire, ever - the number represents seconds
collection.configure({ expireKeys: 0 });

collection.set('ThisIsMyKey', { a: 0, b: 'Hiya', c: { d: 99}}, function(err) {
  if (err) {
    console.error('There was an error');
    return;
  }

  collection.get('ThisIsMyKey', function(err, obj) {
    if (err) {
      console.error('There was an error in collection.get.');
      return;
    }

    console.log('The object: ',obj);
  });
});
```

## API documentation

### store.collection(name)

Returns a Collection object which lets you share data between node processes.

### Class: Collection

A `Collection` instance provides access to a shared key-value store
shared by multiple node instances.

How collections are named and stored is determined by the storage backend. The
`strong-store-cluster` implementation stores collections in the master process
(if you're using cluster), and accepts any arbitrary string as a collection
name.

A `Collection` object is also an `EventEmitter`.


#### collection.configure([options])

* `options` (`Object`) contains configurations options to be changed
  * `expireKeys` (`Number`) seconds after which keys in this
    collection are to be expired.

Set configuration options for the collection.

Currently only one configurable option is supported: `expireKeys`. When set
to a nonzero value, keys will automatically expire after they've not been
read or updated for some time. The timeout is specified in seconds. There's no
guarantee that the key will be discared after exactly that number of seconds
has passed. However keys will never be automatically deleted _sooner_ than what
the `expireKeys` setting allows.

It is perfectly legal to call the `configure` method from multiple node
processes (e.g. both in a worker and in the master process). However you
should be careful to set the _same_ option values every time, otherwise the
effect is undefined.


#### collection.get(key, callback)

* `key` (`String`) key to retrieve
* `callback` (`Function`) called when the value has been retrieved

Read the value associated with a particular key. The callback is called with
two arguments, `(err, value)`. When the key wasn't found in the collection, it
is automatically created and it's `value` is set to `undefined`.


#### collection.set(key, [value], [callback])

* `key` (`String`) key to set or update
* `value` (`object`) value to associate with the key
* `callback` (`Function`) called when the value has been retrieved

Set the value associated with `key`. The `value` must be either undefined or
a value that can be serialized with JSON.stringify.

When the `value` parameter is omitted or set to `undefined`, the key is
deleted, so effectively it's the same as calling `collection.del(key)`.

The `callback` function receives only one argument, `err`. When the
callback is omitted, the master process does not send a confirmation
after updating the key, and any errors are silently ignored.


#### collection.del(key, [callback])

* `key` (`String`) key to delete
* `callback` (`Function`) called when the value has been retrieved

Delete a key from the collection.

This operation is the equivalent of setting the key to `undefined`.

The `callback` function receives only one argument, `err`. When the
callback is omitted, the master process does not send a confirmation
after deleting the key, and any errors are silently ignored.


#### collection.acquire(key, callback)

* `key` (`String`) key to delete
* `callback` (`Function`) called when the key has been locked

Lock a key for exclusive read and write access.

The `acquire` methods waits until it can grab an exclusive lock on the
specified key. When the lock is acquired, no other process can read, write or
delete this particular key. When the lock is no longer needed, it should be
relinquished with `keylock.release()`.

Three parameters are passed to the `callback` function:
`(err, keylock, value)`. The `keylock` argument receives a `KeyLock` class
instance, which lets you read and manipulate the key's value as well as
eventually release the lock. The `value` argument is set to the initial value
associated with the key.


#### Event: 'error'

* `err` (`Error`)

The error event is emitted whenever an unrecoverable error is encountered.

### Class: KeyLock

A `KeyLock` instance represents a key that has been locked. The `KeyLock`
class implements methods that lets you manipulate the key and release
the lock.


#### keylock.get()

* Returns: (`Object`) value that's currently associated with the key

This function returns the value that's currently associated with the locked
key.

Initially this is the same as the `value` argument that was passed to the
`collection.acquire()` callback, but it does immediately reflect changes that
are made with `keylock.set()` and `keylock.del()`.


#### keylock.set([value])

Updates the value associated with a locked key.

The change isn't pushed back to the master process immediately; the change
is committed when the lock is released again. The change however is reflected
immediately in the return value from `keylock.get()`.

After the lock has been released, the key can no longer be updated through the
`KeyLock` instance. Any attempt to do so will make it throw.

Setting the value to `undefined` marks the key for deletion, e.g. it's
equivalent to `keylock.del()`.


#### keylock.del()

Mark a locked key for deletion. See `keylock.set()`.


#### keylock.release([callback])

Release the lock that protects a key. If the key was updated with
`keylock.set()` or `keylock.del()`, these changes are committed.

When a lock has been released, it is no longer possible to manipulate the
key using `KeyLock` methods. Releasing the lock twice isn't allowed either.
The `get()` method will still work but it won't reflect any value changes
that were made after releasing.

The `callback` function receives only one argument, `err`. When the
callback is omitted, the master process does not send a confirmation
after releasing the key, and any errors are silently ignored.