Deprecate lockfile.Locker.RecursiveLock

It is not valid as currently implemented, and there is no known user.

Signed-off-by: Miloslav Trmač <[email protected]>

containers.go

@@ -617,6 +617,8 @@ func (r *containerStore) Lock() {
 	r.lockfile.Lock()
 }
 
+// Deprecated: This can block indefinitely if the current goroutine owns the lock, and another goroutine is trying to acquire a writer lock.
+// Do not use this.
 func (r *containerStore) RecursiveLock() {
 	r.lockfile.RecursiveLock()
 }

images.go

@@ -798,6 +798,8 @@ func (r *imageStore) Lock() {
 	r.lockfile.Lock()
 }
 
+// Deprecated: This can block indefinitely if the current goroutine owns the lock, and another goroutine is trying to acquire a writer lock.
+// Do not use this.
 func (r *imageStore) RecursiveLock() {
 	r.lockfile.RecursiveLock()
 }

layers.go

@@ -1895,6 +1895,8 @@ func (r *layerStore) Lock() {
 	r.lockfile.Lock()
 }
 
+// Deprecated: This can block indefinitely if the current goroutine owns the lock, and another goroutine is trying to acquire a writer lock.
+// Do not use this.
 func (r *layerStore) RecursiveLock() {
 	r.lockfile.RecursiveLock()
 }

pkg/lockfile/lockfile.go

@@ -19,6 +19,9 @@ type Locker interface {
 
 	// Acquire a writer lock recursively, allowing for recursive acquisitions
 	// within the same process space.
+	//
+	// Deprecated: This can block indefinitely if the current goroutine owns the lock, and another goroutine is trying to acquire a writer lock.
+	// Do not use this.
 	RecursiveLock()
 
 	// Unlock the lock.

pkg/lockfile/lockfile_unix.go

@@ -143,8 +143,13 @@ func (l *lockfile) lock(lType int16, recursive bool) {
 		l.rwMutex.RLock()
 	case unix.F_WRLCK:
 		if recursive {
-			// NOTE: that's okay as recursive is only set in RecursiveLock(), so
-			// there's no need to protect against hypothetical RDLCK cases.
+			// WARNING: This is invalid according to the sync.RWMutex API:
+			// sync.RWMutex must not be used recursively, because
+			// RLock() will block on a goroutine that owns the lock already
+			// if there is another goroutine blocked in rwMutex.Lock().
+			//
+			// Recursive is only set in RecursiveLock(), so we only need to check
+			// “recursive” in the unix.F_WRLCK case.
 			l.rwMutex.RLock()
 		} else {
 			l.rwMutex.Lock()
@@ -187,6 +192,9 @@ func (l *lockfile) Lock() {
 // RecursiveLock locks the lockfile as a writer but allows for recursive
 // acquisitions within the same process space.  Note that RLock() will be called
 // if it's a lockTypReader lock.
+//
+// Deprecated: This can block indefinitely if the current goroutine owns the lock, and another goroutine is trying to acquire a writer lock.
+// Do not use this.
 func (l *lockfile) RecursiveLock() {
 	if l.ro {
 		l.RLock()

pkg/lockfile/lockfile_windows.go

@@ -1,3 +1,4 @@
+//go:build windows
 // +build windows
 
 package lockfile
@@ -36,6 +37,8 @@ func (l *lockfile) Lock() {
 	l.locked = true
 }
 
+// Deprecated: This can block indefinitely if the current goroutine owns the lock, and another goroutine is trying to acquire a writer lock.
+// Do not use this.
 func (l *lockfile) RecursiveLock() {
 	// We don't support Windows but a recursive writer-lock in one process-space
 	// is really a writer lock, so just panic.