azmutex

README

Distributed Mutex on Azure Lease Blobs

This package implements distributed lock available for multiple processes. Possible use-cases include exclusive access to shared data, leader election, etc.

Azure Storage supports the feature that guarantees exclusive access to the blobs using basic lease functionality: it's possible to acquire a fixed or infinite duration lease, renew and then release it. Thus it's possible to implement a basic distributed mutex on top of blobs.

Basic Abstractions

AzureMutex

A wrapper on top of Azure blobs API encapsulates API interactions and provides three primary functions: Acquire, Renew, Release.

Locker

Top-level abstractions that support background renewal of the acquired lease.

Locker Usage

Installation

go get -u github.com/youscan/go-azuremutex

Configuration

var options = azmutex.MutexOptions{
	AccountName:   "mystorageaccount",
	AccountKey:    "******",
	ContainerName: "locks",
}

Use Locker with automated renewal

locker := azmutex.NewLocker(options, "migration")

err = locker.Lock()
...
// As soon the lease was acquired we can safely do exclusive job
RunDatabaseMigration()
...
err = locker.Unlock()

Use AzureMutex with lease that will expire in 60 seconds

mutex := azmutex.NewMutex(options)

err = mutex.Acquire("migration", 60)
...
// This code is only safely to run within 60 seconds window
RunDatabaseMigration()
...
err = mutex.Release("migration")

Reference

• Azure / Architecture / Cloud Design Patterns / Leader Election pattern
• Microsoft Azure Development Cookbook Second Edition: Leasing a blob and implementing distributed locks

Documentation

Index

• type AzureMutex
  • func NewMutex(options MutexOptions) *AzureMutex
  • func NewMutexWithContext(options MutexOptions, ctx context.Context) *AzureMutex
  • func (m *AzureMutex) Acquire(key string, leaseDuration int32) error
  • func (m *AzureMutex) Release(key string) error
  • func (m *AzureMutex) Renew(key string) error
• type LeaseAlreadyPresentError
  • func NewLeaseAlreadyPresentError(err error) *LeaseAlreadyPresentError
  • func (e *LeaseAlreadyPresentError) Error() string
• type Locker
  • func NewLocker(options MutexOptions, key string) *Locker
  • func (l *Locker) Lock() error
  • func (l *Locker) Unlock() error
• type MutexOptions

Types

type AzureMutex

type AzureMutex struct {
	// contains filtered or unexported fields
}

func NewMutex

func NewMutex(options MutexOptions) *AzureMutex

func NewMutexWithContext

func NewMutexWithContext(options MutexOptions, ctx context.Context) *AzureMutex

func (*AzureMutex) Acquire

func (m *AzureMutex) Acquire(key string, leaseDuration int32) error

func (*AzureMutex) Release

func (m *AzureMutex) Release(key string) error

func (*AzureMutex) Renew

func (m *AzureMutex) Renew(key string) error

type LeaseAlreadyPresentError

type LeaseAlreadyPresentError struct {
	Err error
}

func NewLeaseAlreadyPresentError

func NewLeaseAlreadyPresentError(err error) *LeaseAlreadyPresentError

func (*LeaseAlreadyPresentError) Error

func (e *LeaseAlreadyPresentError) Error() string

type Locker

type Locker struct {
	// contains filtered or unexported fields
}

func NewLocker

func NewLocker(options MutexOptions, key string) *Locker

func (*Locker) Lock

func (l *Locker) Lock() error

func (*Locker) Unlock

func (l *Locker) Unlock() error

type MutexOptions

type MutexOptions struct {
	AccountName        string
	AccountKey         string
	ContainerName      string
	UseStorageEmulator bool
	LogFunc            func(message string)
}