README
¶
DocLock - A locking Go library for cloud
A simple binary lock (mutex) library built on top of Docstore (Firestore, DynamoDB or MongoDB): https://gocloud.dev/howto/docstore/
Locks can be used for leader election or more custom use cases. Locks have a TTL and each resource has its own document in the collection. Locks acquire a specific Resource ID.
Usage
//...
import "github.com/bgadrian/doclock"
import "gocloud.dev/docstore"
//...
func(){
resourceID := "my_server_leader"
//the collection needs to have the Key ID set `id`, you can use the constant KEY
var myDataStoreCollection *docstore.Collection
//blocks until acquired
leaderLock := doclock.New(myDataStoreCollection, resourceID).Build()
leaderCh, _ := leaderLock.Lock(context.Background())
//do your leader stuff while leaderCh is open
//when shutting down call to release the lock
leaderLock.Unlock()
}
Contribute
Requirements
Go 1.16+
go install github.com/golang/mock/mockgen
Documentation
¶
Index ¶
- Constants
- Variables
- func WrapLockWithLeader(ctx context.Context, l *Lock, actor Leader)
- type Collection
- type Doc
- type Leader
- type Lock
- type LockBuilder
- func (b *LockBuilder) Build() *Lock
- func (b *LockBuilder) WithActorID(d uint64) *LockBuilder
- func (b *LockBuilder) WithLeaseTTL(d time.Duration) *LockBuilder
- func (b *LockBuilder) WithLeaseTTLUpdateInterval(d time.Duration) *LockBuilder
- func (b *LockBuilder) WithLockPollDuration(d time.Duration) *LockBuilder
Constants ¶
const KEY = "id"
KEY is the collection name of the Key property.
Variables ¶
var ( ErrLockHeld = errors.New("lock already held") ErrNotHeld = errors.New("lock not held") )
Functions ¶
Types ¶
type Collection ¶
type Collection interface {
Put(ctx context.Context, doc docstore.Document) error
Delete(ctx context.Context, doc docstore.Document) error
Get(ctx context.Context, doc docstore.Document, fps ...docstore.FieldPath) error
}
Collection is a subset of methods of *docstore.Collection TODO make this more abstract, and implement a wrapper to use any other storage
type Doc ¶
type Doc struct {
ID string `docstore:"id"` //the resourceID
ExpirationTime time.Time `docstore:"ex_ts"`
ExpirationActor uint64 `docstore:"ex_actor"`
//for optimistic concurrency
DocstoreRevision interface{}
}
Doc is the internal document. Exported only for marshalling.
type Lock ¶
type Lock struct {
// contains filtered or unexported fields
}
type LockBuilder ¶
type LockBuilder struct {
// contains filtered or unexported fields
}
func New ¶
func New(collection Collection, resourceID string) *LockBuilder
func (*LockBuilder) WithActorID ¶
func (b *LockBuilder) WithActorID(d uint64) *LockBuilder
WithActorID sets a custom ActorID. It is not recommended!
func (*LockBuilder) WithLeaseTTL ¶
func (b *LockBuilder) WithLeaseTTL(d time.Duration) *LockBuilder
WithLeaseTTL sets a custom TTL for the lock
func (*LockBuilder) WithLeaseTTLUpdateInterval ¶
func (b *LockBuilder) WithLeaseTTLUpdateInterval(d time.Duration) *LockBuilder
WithLeaseTTLUpdateInterval sets a custom update rate of the extension of lease/TTL A document.Update with now+LeaseTTL will be called at each tick, while the lock is acquired.
func (*LockBuilder) WithLockPollDuration ¶
func (b *LockBuilder) WithLockPollDuration(d time.Duration) *LockBuilder
WithLockPollDuration sets a custom maximum duration between 2 attempts to acquire the lock
Source Files
Directories