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.
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
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
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.
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
By locks every thing named, in this set, until unlock is called (see the package's By).
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.