# Locks API for Go

Every public type, function and constant of the Locks engine in `tinyshed.org/tinystore/locks`, generated from its source. The [Locks guide](https://tinyshed.org/tinystore/docs/guides/locks) explains how to use them, and the [Bun and Node](https://tinyshed.org/tinystore/docs/reference/bun/locks), [Python](https://tinyshed.org/tinystore/docs/reference/python/locks) and [Rust](https://tinyshed.org/tinystore/docs/reference/rust/locks) pages list the same API.

## Fence

```go
type Fence struct {
	// contains filtered or unexported fields
}
```

Fence grows with every lease the store gives a lock, 128 bits: hand it to whatever must refuse a late holder, which keeps the greatest it saw.

### Fence.Less

```go
func (f Fence) Less(other Fence) bool
```

Less says f came before other.

### Fence.String

```go
func (f Fence) String() string
```

String is the fence in decimal, as the store writes it.

## HoldOption

```go
type HoldOption func(*time.Duration)
```

HoldOption is how a hold waits.

### Wait

```go
func Wait(d time.Duration) HoldOption
```

Wait is how long a hold waits in line for its key, 10 s unless given: a key still held past it is ErrInUse.

## Lease

```go
type Lease struct {
	Fence Fence
}
```

Lease is a holding of a key: a lock's Fence, none for a semaphore's.

## Lock

```go
type Lock struct {
	// contains filtered or unexported fields
}
```

Lock is keys held one holder at a time.

### OpenLock

```go
func OpenLock(store *tinystore.Store, name string, opts ...Option) (*Lock, error)
```

OpenLock opens a lock: keys held one holder at a time, across every program of the store.

### Lock.Hold

```go
func (l *Lock) Hold(ctx context.Context, key any, fn func(ctx context.Context, lease *Lease) error, opts ...HoldOption) error
```

Hold waits for key in line, holds it while fn runs and lets it go. A key still held past the wait is ErrInUse; a lease lost while fn ran ends its ctx, and Hold is ErrLost though fn succeeded, since another holder may have run beside it.

### Lock.TryHold

```go
func (l *Lock) TryHold(ctx context.Context, key any, fn func(ctx context.Context, lease *Lease) error) (bool, error)
```

TryHold holds key while fn runs if nobody holds it, and says whether it did.

## Option

```go
type Option func(*keys)
```

Option is how a lock or a semaphore opens.

### Limit

```go
func Limit(n int) Option
```

Limit is how many may hold a semaphore's key at once, 1 to 1000.

### MaxHold

```go
func MaxHold(d time.Duration) Option
```

MaxHold is how long a lease lasts from its grant, however it is renewed: past it the next in line holds the key, and the holder's ctx ends.

### TTL

```go
func TTL(d time.Duration) Option
```

TTL is how long a lease lasts from its last renewal, 1 s to 1 hour, 10 s unless given; this program renews it at a third of it while the function runs.

## Semaphore

```go
type Semaphore struct {
	// contains filtered or unexported fields
}
```

Semaphore is keys held by up to their limit at a time.

### OpenSemaphore

```go
func OpenSemaphore(store *tinystore.Store, name string, opts ...Option) (*Semaphore, error)
```

OpenSemaphore opens a semaphore: each key held by up to Limit holders at once.

### Semaphore.Hold

```go
func (s *Semaphore) Hold(ctx context.Context, key any, fn func(ctx context.Context, lease *Lease) error, opts ...HoldOption) error
```

Hold waits for one of key's permits in line and holds it while fn runs, as a lock's Hold does.

### Semaphore.TryHold

```go
func (s *Semaphore) TryHold(ctx context.Context, key any, fn func(ctx context.Context, lease *Lease) error) (bool, error)
```

TryHold holds one of key's permits while fn runs if one is free, and says whether it did.