Class: DSMServer

Clusterluck.DSMServer(gossip, kernel, optsopt)

new DSMServer(gossip, kernel, optsopt)

Distributed semaphore-manager server. Semaphores are created/read/destroyed, as well as posted/closed (grabbing the semaphore/releasing the sempahore). Unlike the DLM, which uses a quorum to determine success of locking, this routes all requests against any semaphore requests to the singular node that 'owns' the semaphore, determined by the hash ring in the hash ring of gossip.

Parameters:
Name Type Attributes Description
gossip Clusterluck.GossipRing

Gossip ring to coordinate ring state from.
kernel Clusterluck.NetKernel

Network kernel to communicate with other nodes.
opts Object <optional>

Options object containing information about disk persistence options, and wait times for retry logic on lock requests.

Properties
Name Type Attributes Description
minWaitTimeout Number <optional>

Minimum amount of time in milliseconds to wait for a retry on a locking request.
maxWaitTimeout Number <optional>

Maximum amount of time in milliseconds to wait for a retry on a locking request.
disk Boolean <optional>

Whether to persist lock state to disk. If true is passed, the following options will be read.
path String <optional>

Path for underlying DTable instance to flush state to.
writeThreshold Number <optional>

Write threshold of underlying DTable instance.
autoSave Number <optional>

Autosave interval of underlying DTable instance.
fsyncInterval Number <optional>

Fsync interval of underlying DTable instance.
compress Boolean <optional>

Whether to feed RDB snapshot streams through a GZIP compression stream for the underlying DTable instance.
name String <optional>

Name of underlying DTable to write to.
Source:

Methods

(static) calculateWaitTime(min, max) → {Number}

Calculates wait time for retry functionality in post requests.

Parameters:
Name Type Description
min Number

Minimum wait time.
max Number

Maximum wait time.
Source:
Returns:

Amount of time to wait.

Type
Number

(static) parseJob(job, command) → {Object|Error}

Parse and validate job for correct structure and type adherence.

Parameters:
Name Type Description
job Object

Job to parse/validate.
command String

Command job corresponds to. This determines which set of static type definitions to validate job against.
Source:
Returns:

An object if successfully parsed/validated, otherwise an Error indicating the reason for failure.

Type
Object | Error

close(id, holder, cb, reqTimeoutopt)

Closes the semaphore id with holder holder. If the request takes longer than reqTimeout, cb is called with a timeout error. Otherwise, cb is called with no arguments. The algorithm consists of:

  • Use the internal gossip server to find the node responsible for id on the hash ring.
  • Make a request to the DSM server on that node to execute the close command.
  • If an error is returned, call cb with that error.
  • Otherwise, call cb with no arguments.
Parameters:
Name Type Attributes Description
id String

ID of semaphore to clsoe.
holder String

ID of actor/requester for this semaphore.
cb function

Function of form function (err) {...}, where err is null if the request is successful, or an Error object otherwise.
reqTimeout Number <optional>

Amount of time, in milliseconds, to wait for a clsoe attempt before considering the request errored. Defaults to Infinity.
Source:

closeAsync(id, holder)

Asynchronously closes the semaphore id with holder holder. The algorithm consists of:

  • Use the internal gossip server to find the node responsible for id on the hash ring.
  • Make an asynchronous request to the DSM server on that node to execute the close command.
Parameters:
Name Type Description
id String
holder String
Source:

create(id, n, cb, reqTimeoutopt)

Creates a semaphore with id id and concurrency limit n. The algorithm consists of:

  • Use the internal gossip server to find the owning node responsible for id on the hash ring.
  • Make a request to the DSM server on that node to create the semaphore.
  • If no error is returned, the request is considered successful and we call cb with no arguments.
  • Otherwise, we return the error in cb.
Parameters:
Name Type Attributes Description
id String

ID of semaphore to create.
n Number

Concurrency limit of semaphore.
cb function

Function of form function (err) {...}. err is null if the request is successful, or an Error object otherwise.
reqTimeout Number <optional>

Amount of time, in milliseconds, to wait for a response before considering the request errored. Defauls to Infinity.
Source:

decodeJob(buf) → {Object|Error}

Parses a fully memoized message stream into an object containing a key/value pair. If we fail to parse the job buffer (invalid JSON, etc), we just return an error and this GenServer will skip emitting an event. Otherwise, triggers user-defined logic for the parsed event.

Parameters:
Name Type Description
buf Buffer

Memoized buffer that represents complete message stream.
Source:
Returns:

Object containing an event and data key/value pair, which are used to emit an event for user-defined logic.

Type
Object | Error

decodeSingleton(data) → {Object|Error}

Parses a singleton message stream into an object containing a key/value pair. If we fail to parse the job object (invalid format for given event value, etc.), we just return an error and this GenServer will skip emitting an event. Otherwise, triggers user-defined logic for the parsed event.

Parameters:
Name Type Description
data Object

Message to be processed with event and data parameters.
Source:
Returns:

Object containing an event and data key/value pair, which are used to emit an event for user-defined logic.

Type
Object | Error

destroy(id, cb, reqTimeoutopt)

Destroys sempahore id, along with all active holders The algorithm consists of:

  • Use the internal gossip server to find the owning node responsible for id on the hash ring.
  • Make a request to the DSM server on that node to destroy the semaphore.
  • If no error is returned, the request is considered successful and we call cb with a null error.
  • Otherwise, we return the error in cb.
Parameters:
Name Type Attributes Description
id String

ID of semaphore to destroy.
cb function

Function of form function (err) {...}. err is null if the request is successful, or an Error object otherwise.
reqTimeout Number <optional>

Amount of time, in milliseconds, to wait for a response before considering the request errored. Defauls to Infinity.
Source:

idle() → {Boolean}

Returns whether this instance is idle or not. Checks for both active requests as well as the underlying table's state for idleness.

Source:
Returns:
Type
Boolean

load(cb)

Loads state from disk for the underlying table this instance uses for state persistence. If the disk option is set to false on construction, this function will immediately return and call cb. NOTE: this function should be called after start is called, as the underlying table needs to be started before any files can be read from disk.

Parameters:
Name Type Description
cb function

Function of the form function (err) {...}, where err will be passed if an error occurs loading state from disk.
Source:

post(id, holder, timeout, cb, reqTimeoutopt, retriesopt)

Makes a post request against semaphore id with holder identifying the requester of this semaphore (think actor). holder should be a randomly generated string if looking for different requests to represent different actions, such as a UUID or the result of a crypto.randomBytes call. The post will last for timeout milliseconds before being automatically released on the node this semaphore routes to. The algorithm consists of:

  • Use the internal gossip server to find the node responsible for id on the hash ring.
  • Make a request to the DSM server on that node to execute the post command.
  • Based on the response, if an 'ok' response is returned within timeout milliseconds, then the request was successful and we return a null error.
  • Otherwise, we asynchronously close this semaphore on the routed node and set a random timeout to retry the request. If we've retried retries number of times, then an error is returned and retry logic ceases.
Parameters:
Name Type Attributes Description
id String

ID of semaphore to post.
holder String

ID of actor/requester for this request.
timeout Number

How long the semaphore observance will last on the node holding this semaphore, in milliseconds.
cb function

Function of form function (err) {...}. err is null if the request is successful, or an Error object otherwise.
reqTimeout Number <optional>

Amount of time, in milliseconds, to wait for a post attempt before considering the request errored. Defaults to Infinity.
retries Number <optional>

Number of times to retry this request. Defaults to Infinity.
Source:

read(id, cb, reqTimeoutopt)

Grabs the current state of sempahore id, which consists of the concurrency limit and the number of active holders of the semaphore. The algorithm consists of:

  • Use the internal gossip server to find the owning node responsible for id on the hash ring.
  • Make a request to the DSM server on that node to read metadata about the semaphore.
  • If no error is returned and the response is valid JSON, the request is considered successful and we call cb with a null error and the metadata returned in the response.
  • Otherwise, we return the error in cb.
Parameters:
Name Type Attributes Description
id String

ID of semaphore to read.
cb function

Function of form function (err, data) {...}, where data is a JSON object of the form {n: <concurrency limit>, active: <number of active holders>}. err is null if the request is successful, or an Error object otherwise.
reqTimeout Number <optional>

Amount of time, in milliseconds, to wait for a response before considering the request errored. Defaults to Infinity.
Source:

start(nameopt) → {Clusterluck.DSMServer}

Starts a DSM handler: listenes for events related to the creation/reading/destruction of semaphores, as well as grabbing/releasing semaphores. Also starts the underlying table storing semaphores and semaphore holders.

Parameters:
Name Type Attributes Description
name String <optional>

Name to register this handler with instead of the unique id attached. Any message received on the network kernwl with id name will be routed to this instance for message stream parsing, and possible event firing.
Source:
Returns:

This instance.

Type
Clusterluck.DSMServer

stop() → {Clusterluck.DSMServer}

Stops this handler. If the table is idle, this function will transition into clearing all locks and table state, and stopping the underlying table. Otherwise, this function will wait to complete until this instance is in an idle state.

Source:
Returns:

This instance.

Type
Clusterluck.DSMServer