lockclient

README

DynamoDB Lock Client - Golang

A golang 1.x implementation of awslabs/dynamodb-lock-client.

The Amazon DynamoDB Lock Client is a general purpose distributed locking library built for DynamoDB. The DynamoDB Lock Client supports both fine-grained and coarse-grained locking as the lock keys can be any arbitrary string, up to a certain length.^[1]

Table of Contents

• Usage
• Documentation
  • lockclient.DynamoDBLockClient
  • GetLock()
  • StopHeartbeat()
  • RemoveLock()
  • HasLock()
  • SetLevel()
• Contributing

Usage

To pull dependencies:

go get github.com/samstradling/dynamodb-lock-client-golang

For a full example see examples/basic-case/main.go.

// Setup AWS region, and, for local development only, the endpoint
config := &aws.Config{
        Region:   aws.String("eu-west-1"),
        Endpoint: aws.String("http://localhost:8000"),
    }
sess := session.Must(session.NewSession(config))
// Setup the lock client config
lockClient := &lockclient.DynamoDBLockClient{
    LockName:        "my-unique-lock-name",
    LeaseDuration:   5000 * time.Millisecond,
    HeartbeatPeriod: 1000 * time.Millisecond,
    TableName:       "LockTable",
    Client:          dynamodb.New(sess),
}

for true {
    err := lockClient.GetLock() // Try to get the lock
    if err != nil {
        break
    }
    // Keep trying every second
    time.Sleep(1 * time.Second)
}
defer lockClient.RemoveLock() // remove the lock once done

for i := 0; i < 10; i++ {
    _, err := lockClient.HasLock() // check if lock is still valid
    if err != nil {
        logrus.Debug(err)
    }
    time.Sleep(1000 * time.Millisecond) // super important action that requires a global lock
}

Documentation

import "github.com/samstradling/dynamodb-lock-client-golang"

To use, create a dynamo table with a hash key named key.

lockclient.DynamoDBLockClient

DynamoDBLockClient creates a new lock client.

lockClient := &lockclient.DynamoDBLockClient{}

DynamoDBLockClient fields:

Field	Type	Description
LockName	string	A unique string that represents the lock required. A client will only compete with other clients presenting the same LockName string.
LeaseDuration	Duration	The time to lease the lock, for the initial request and every renewal.
HeartbeatPeriod	Duration	The time between renewals of the lock. At maximum should be LeaseDuration / 2.
TableName	string	DynamoDB table name.
Identifier	string	Used for uniquely identifying the client. If unset a random one is generated using uuid.NewRandom()
Client	*DynamoDB	DynamoDB client used for the connection.

GetLock()

Request a new lock, returns true on success.

func (d *DynamoDBLockClient) GetLock() (bool, error)

StopHeartbeat()

Stop sending lock heartbeats, any existing locks will not be removed until they expire.

func (d *DynamoDBLockClient) StopHeartbeat()

RemoveLock()

Request the removal of any existing locks.

func (d *DynamoDBLockClient) RemoveLock() error

HasLock()

Returns true if the existing lock is valid.

func (d *DynamoDBLockClient) HasLock() (bool, error)

SetLevel()

This library uses github.com/sirupsen/logrus. To set the log level use:

logrus.SetLevel(logrus.DebugLevel)
logrus.SetLevel(logrus.InfoLevel)
logrus.SetLevel(logrus.ErrorLevel)

Contributing

To develop locally you'll probably want to run a local version of dynamodb. This can be done with the following docker command:

docker run -p 8000:8000 -d amazon/dynamodb-local

The examples directory contains a script to create a local dynamodb table:

go run examples/create-local-table/main.go

Contibutions welcomed.

Documentation

Index

• type DynamoDBLockClient
  • func (d *DynamoDBLockClient) GetLock() (bool, error)
  • func (d *DynamoDBLockClient) HasLock() (bool, error)
  • func (d *DynamoDBLockClient) LockError() error
  • func (d *DynamoDBLockClient) RemoveLock() error
  • func (d *DynamoDBLockClient) StopHeartbeat()
• type LockClient

Types

type DynamoDBLockClient

type DynamoDBLockClient struct {
	LockName        string
	LeaseDuration   time.Duration
	HeartbeatPeriod time.Duration
	TableName       string
	Identifier      string
	Client          dynamodbiface.DynamoDBAPI
	// contains filtered or unexported fields
}

DynamoDBLockClient describes the fields for a lock client

func (*DynamoDBLockClient) GetLock

func (d *DynamoDBLockClient) GetLock() (bool, error)

GetLock requests a lock, and returns a lock on failure

func (*DynamoDBLockClient) HasLock

func (d *DynamoDBLockClient) HasLock() (bool, error)

HasLock returns true if the lock is still valid

func (*DynamoDBLockClient) LockError

func (d *DynamoDBLockClient) LockError() error

LockError returns a lock error if the heartbeat thread found one

func (*DynamoDBLockClient) RemoveLock

func (d *DynamoDBLockClient) RemoveLock() error

RemoveLock removes the existing lock

func (*DynamoDBLockClient) StopHeartbeat

func (d *DynamoDBLockClient) StopHeartbeat()

StopHeartbeat stops sending lock renewal heartbeats, consider using RemoveLock

type LockClient

type LockClient interface {
	GetLock() (bool, error)
	HasLock() (bool, error)
	StopHeartbeat()
	RemoveLock() error
}

LockClient interface names the method signatures for implementing a DynamoDB Lock Client