lock

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2026 License: GPL-3.0 Imports: 5 Imported by: 1

Documentation

Overview

Package lock makes the callers in one process take turns at a thing, so one does not undo another's change to it.

A tool that edits a record by reading it whole and sending it back - no server it talks to has a conditional update - loses a change when two such edits run at once: each sends back what it read, and the later one undoes the earlier. An MCP client runs the calls of one turn at once, so eight calls each adding a tag to one book left one tag. Locking the record for the whole read and write keeps them apart:

unlock := lock.By(playlist)
defer unlock()
// read the playlist again, change it, send it back

By locks whatever it is handed, any mix of things in one call:

lock.By(item)                                 // this record
lock.By(lock.ID[Item](id))                    // the same record, with only its id in hand
lock.By(item, lock.Field(me, "bookmarks"))    // a record, and a named piece of another
lock.By(lock.String("server settings"))       // something with no record behind it

A record is locked as its type and its id, never as the Go value: two callers each fetch their own copy of one record, and both copies must come to the same lock. So a type that can be locked says which record a value is, with one method:

func (it *Item) LockID() string { return it.ID }

All locks everything, for a change that reads a whole collection and writes it back.

One set, or a set of your own

By, ByString and All work on one set of locks that every caller in the process shares. That is right for a process that is one world: one server, where a record's id means the same thing to every caller. A process that holds several worlds - two servers that each have an item 12, or a test run of many fake servers - either says which world in the key, as ByString(server + " " + id) does, or gives each world a set of its own with NewSet, whose By, ByString and All reach no further than that set. A set of its own is the only way to keep one world's All from holding up the others.

Another client of the same server, its own web app included, is never held back: these locks are this process's alone.

One call at a time

A caller locks once at a time, naming everything it needs in that one call. Whatever is named is taken in one order, so two callers that want overlapping things cannot each hold what the other waits for. Locking a second time while holding the first gives that up, and can also wait on an All that is itself waiting for the first to be unlocked.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func All

func All() (unlock func())

All locks everything there is or could be, for a change that reads a whole collection and writes it back: it waits for every other lock to be unlocked, and none is granted until it is.

func By added in v0.5.0

func By(things ...Thing) (unlock func())

By locks every thing named until unlock is called, waiting for whoever has any of them. They are taken in one order, each once however often it is named, so two callers locking overlapping things cannot wait on each other for ever. Naming nothing locks nothing.

func ByString added in v0.5.0

func ByString(key string) (unlock func())

ByString locks the thing known by this string: By(String(key)).

Types

type Key added in v0.5.0

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

Key is a thing to lock that is described, where there is no value of it to hand over: a record by its id (ID), a named piece of a thing (Field), or a plain string (String).

func Field added in v0.5.0

func Field(of Thing, name string) Key

Field is a named piece of a thing that is changed on its own: an account's list of bookmarks, a server's settings. It is another lock from the thing itself, and from its other fields.

func ID added in v0.5.0

func ID[T any](id string) Key

ID is the record of type T with this id, for a caller that has not fetched it: By(ID[Item](id)) and By(item) are one lock when item.LockID() is id.

func String added in v0.5.0

func String(s string) Key

String is a thing known only by a string of the caller's own making. It is no record's lock, whatever the string says.

func (Key) LockID added in v0.5.0

func (k Key) LockID() string

LockID is what the key names, written out, so a Key is itself a Thing.

type Set added in v0.5.0

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

Set is a set of locks of its own: what is locked in one set holds nobody up in another, All included. An application that serves one world from one process can use the package's own By, ByString and All, which share one set; one that holds several, or a test that wants to see nothing was left locked, makes a set with NewSet. The zero value is ready to use.

A set keeps a lock for a key only while somebody holds or waits for it, so a long-running server does not keep one for every record it ever touched.

func NewSet added in v0.5.0

func NewSet() *Set

NewSet returns a set of locks that shares nothing with any other.

func (*Set) All added in v0.5.0

func (s *Set) All() (unlock func())

All locks everything there is or could be in this set: it waits for every lock in it to be unlocked, and none is granted until it is.

func (*Set) By added in v0.5.0

func (s *Set) By(things ...Thing) (unlock func())

By locks every thing named, in this set, until unlock is called (see the package's By).

func (*Set) ByString added in v0.5.0

func (s *Set) ByString(key string) (unlock func())

ByString locks the thing known by this string, in this set.

func (*Set) Idle added in v0.5.0

func (s *Set) Idle() bool

Idle reports whether nothing in the set is locked and nobody waits for anything in it: what a test asks once every call it made has returned, to see that none left a lock behind.

type Thing added in v0.5.0

type Thing interface {
	// LockID is the id of the record this value is a copy of. It is
	// compared as it is written, so a type whose server reads one id in
	// several spellings folds them to one here.
	LockID() string
}

Thing is what By locks: a value that says which record it is. The lock is on the value's type and that id, so two values of one type with one id are one thing, and a playlist and a collection that are both number 12 are two.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL