Skip to content

Latest commit

 

History

History
152 lines (101 loc) · 5.47 KB

api.md

File metadata and controls

152 lines (101 loc) · 5.47 KB

store.collection(name)

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

Collection class

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.

Methods

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.

Events

'error'

  • err (Error)

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

KeyLock class

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.

Methods

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.