@tpietzsch I added logic to handle cleanup of references, including stale references that were not released. I'll try and describe a bit here.

FileKeyLockManager is a package-private singleton instance now, with static fields for the backing map. when a path is requested with lockFor(Reading/Writing) we store a PhantomReference to that LockedFileChannel. On close, the LockedFileChannel will unlock as expected. if it is never closed, we call clearQueue before each further attempt to lock a new path, which will poll the ReferenceQueue<LockedFileChannel> and for any LockedFileChannel that have since been GCd, we release the underlying KeyLockState. Whether this releases the fileLock, or removed the KeyLockState from the map is dependant on whether there are remainin locks on the KeyLockState still. However, KeyLockState is now package private, so it should not be possible to ever try to lock/unlock except through the lockForReading/Writing methods on the FileSystemKeyValueAccess

One caveat to the current implementation; we only clearQueue either on an attempt to lockForReading/Writing of a key, or when a LockedFileChannel is closed properly. This means that possibly if the last LockedFileChannel was not closed, and there are no future calls to lockForReading/lockForWriting then the JVM will retain that file lock. There isn't a great way to solve this. The only guaranteed way would be to occasionally poll the ReferenceQueue in another thread, and clear when it is GCd. That would introduce a daemon thread to n5 core though, which I think is not ideal.

Again, all of this is only to handle the case where a declared AutoCloseable is not closed. I think it's worth being defensive to some degree, but the FileKeyLockManager should already gaurantee that stale locks are only ever a consequence of a developer ignoring the AutoCloseable contract

I revised locking so that locks are not tied to the locking thread. (A LockedChannel can be created by one thread and then be released by another thread). This required to replace ReentrantReadWriteLock by manual reader/writer counting guarded by Semaphores.

I revised clean-up of stale KeyLockStates by putting WeakReferences in the ConcurrentHashMap and adding a ReferenceQueue to remove entries whose KeyLockState has been GCed.

I put no special logic to handle leaked LockedFileChannels (that are abandoned without being properly closed). Surprisingly, this still works. When the KeyLockState is GCed, its associated ChannelLock along with the existing FileChannel and FileLock is also GCed. At least on MacOS, this causes the JVM to release the system-level lock, and everything works out fine.