Quorum client in native perl
Perl
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib/Quorum
t
.gitignore
Changes
LICENSE
Makefile
README.pod

README.pod

NAME

Quorum::Lease - perl representation of a quorum lease. This is meant to be a client to the Quorum service found here: http://github.com/jayjanssen/Quorum.

SYNOPSIS

use Quorum::Lease;

my $lease = Quorum::Lease->new( 
 name => '/test',
 namespace => '/my/namespace'
);

die "Can't acquire lease!" 
  if $lease->isOwned();

if( $lease->acquire( length => 60, retry => 3 )) {
  # lease acquired
  unless( $lease->renew( retry => 3 )) {# renew the lease
    # lease lost
  } else {
    $lease->release();
    # lease released
  }
}

DESCRIPTION

This is a pure-Perl blocking BCP Quorum REST client module. This module abstracts the REST API into a set of simple function calls.

The provided quorum_url and version defines where to access the service over HTTP. All methods directly call the Quorum service, there is no local caching of the Lease record.

High Availability

The quorum_url hostname should be a rotation of REST hosts, preferably one that returns at least two A records. All HTTP calls made by this module are retried once (by default, configurable) if a 5xx error code is returned.

METHODS

Quorum::Lease->new( namespace => '/my/namespace', name => '/lease/id', [option => val, ...])

    Creates a new Quorum::Lease object with the specified options.

    • namespace - The namespace for this lease. *required*

    • name - The lease identifier in the namespace. *required*

    • client_id - string to uniquely indentify this client to the Quorum Service. Defaults to the ip the Quorum service sees when we connect to it (could be through a NAT).

Common Arguments

    All methods (besides 'new') can take some common arguments.

    • retry - Number of times to retry on a server-side error (i.e., 500 error code and up). Final result is what is returned from the function. Acceptable values from 0 - 10. Default: 1 (i.e., two attempts are made)

      This provides a measure of high availability assuming the DNS lookup on the quorum service returns multiple A records.

    • retry_interval - amount of time to wait before retrying again. Defaults to 1 second.

$lease->url()

    Returns the full url for the lease

$lease->isOwned()

    Returns a boolean based on if the lease is acquired or not (by anyone).

$lease->amOwner()

    Returns a boolean based on if the lease is (or was) owned by us. Combine with isOwned to know if the lease is current *and* owned by us.

$lease->expires()

    Returns the unixtime correct to the local server time that the lease will expire. This will work even if the Quorum service is down (last known expiration time), as long as our process had made at least one successful Quorum request in the past.

$lease->seconds_left()

    Returns the number of seconds left on the current lease. Undef if it doesn't know, or lease isn't valid.

$lease->length()

    Returns the last length used for the lease (valid or not).

$lease->seconds_to_renew()

    Amount of time before you should renew. This only works on an active lease.

    The accepted formula is 1/2 the lease length. Undef if the lease isn't valid.

$lease->acquire( [option => val, ...])

    Attempts to acquire the lease with the given options. Returns true if it was successful, false if someone else got there first. Croaks on other errors, including if you already own the lease (renew instead in that case).

    • length - Length of time until the lease expires (in seconds).

    • client_object - Object to be stored in the leasing system, will be returned in the http body on a normal GET (with no Accept: headers). Anyone can request this object. It is also size-restricted in the Quorum REST system.

    • block_for - Tells the method to block for up to the specified number of seconds or until it successfully acquires the lease, whichever comes first. The method will attempt to acquire the lease block_attempts_per_length times (default: 4) every length until it either is successful or the time is up.

      Each attempt to acquire the lease will be subject to the normal retry parameters above.

      A value of -1 tells the method to never stop trying until it acquires the lease. A value of 0, or simply omitting this parameter means the method will not block (except for the normal retry parameters above>).

      If this is specified the method will not return except with a true result, but it can croak on a 4xx (client-side) error (except a 409 lease conflict).

    • block_attempts_per_length - How many tries to make while blocking per length. Default: 4

$lease->renew( [option => val, ...])

    Attempts to renew the lease with the given options. Returns true if it was successful, false if we don't own the lease anymore, croaks on other unexpected errors.

    • client_object - same as acquire

    • block_until_expires - If the client becomes isolated from the Quorum system, the lease will eventually expire because the client cannot renew. If this is set to true, then this method will repeatedly attempt to renew until the lease expires.

      This only works if the client process was able to acquire or renew successfully, which will cause this object to know when the lease should expire. Since only this client should be able to renew, that expiration time should hold true if we can't renew.

      This will return either a true because the lease was renewed, false because the lease got taken over somehow, or croak after the last known expires time passes.

    • block_sleep - Amount of time (in seconds) to sleep before we try to renew again ( (on top of the retry and retry_delay)). Defaults to 5 seconds.

$lease->release( [option => val, ...])

    Attempts to release the lease with the given options. Returns true if it was successful, false if it failed, but we don't own the lease anymore anyway, croaks on other unexpected errors.

    • block_until_expires - same as for renew.

    • block_sleep - same as for renew.

$lease->toString();

    Returns a string representation of the lease from the Quorum server. Probably only useful for debugging purposes.

$lease->toJSON();

    Returns a string representation of the lease from the Quorum server. Probably only useful for debugging purposes.

REST API

The Quorum REST service documentation can be found here: http://github.com/jayjanssen/Quorum

AUTHORS

Jay Janssen <jayj@yahoo-inc.com>