Rework IoPolicy

Make IoPolicy an enum that just communicates the
intented locking behaviour (STRICT, PERMISSIVE,
UNSAFE). How exactly this is implemented is up to the backend.

For the FileSystemKeyValueAccess, the IoPolicy is
simply to the FileKeyLockManager, then on to the
FileLockState, and finally the ChannelLock, which
actually implements the behaviour using FileLock
(or not).

Author: tpietzsch

src/main/java/org/janelia/saalfeldlab/n5/ChannelLock.java

@@ -18,13 +18,22 @@ class ChannelLock implements Closeable {
 
 	private final FileChannel channel;
 
-	//Used to ensure a hard reference exists until we close
+	/**
+	 * Hold a hard reference to the {@code FileLock} to make sure it is not
+	 * prematurely released.
+	 * <p>
+	 * NB: We do not call {@code lock.release()} in {@link #close}, because at
+	 * this point the channel might be already closed (by an external writer).
+	 * {@code lock.release()} will throw an exception if the channel is already
+	 * closed. Instead, we just close the channel which will automatically
+	 * release the lock.
+	 */
 	@SuppressWarnings({"unused", "FieldCanBeLocal"})
-    private final FileLock unusedHardRef;
+	private final FileLock lock;
 
 	private ChannelLock(final FileChannel channel, final FileLock lock) {
 		this.channel = channel;
-		this.unusedHardRef = lock;
+		this.lock = lock;
 	}
 
 	public void close() throws IOException {
@@ -56,9 +65,12 @@ FileChannel getChannel() {
 	 * @throws IOException if an error occurs while opening the channel, or if
 	 * the calling thread is interrupted while waiting for the {@code FileLock}.
 	 */
-	static ChannelLock lock(final Path path, final boolean forWriting) throws IOException {
+	static ChannelLock lock(final Path path, final boolean forWriting, final IoPolicy policy) throws IOException {
 
 		final FileChannel channel = openFileChannel(path, forWriting);
+		if (policy == IoPolicy.UNSAFE) {
+			return new ChannelLock(channel, null);
+		}
 		try {
 			while (true) {
 				try {
@@ -74,34 +86,12 @@ static ChannelLock lock(final Path path, final boolean forWriting) throws IOExce
 				}
 			}
 		} catch (Exception e) {
-			closeQuietly(channel);
-			throw e;
-		}
-	}
-
-	/**
-	 * Create a {@link FileChannel} on the given {@code path} and try to lock it
-	 * with a system-level {@link FileLock}. If the channel cannot be locked,
-	 * {@code null} is returned.
-	 * <p>
-	 * The {@code FileLock} is exclusive if the {@code path} is locked {@code
-	 * forWriting}, and shared otherwise.
-	 * <p>
-	 * If the {@code path} is locked {@code forWriting} non-existing file and
-	 * the parent directories are created as needed.
-	 *
-	 * @throws IOException if an error occurs while opening the channel.
-	 */
-	static ChannelLock tryLock(final Path path, final boolean forWriting) throws IOException {
-
-		FileChannel channel = null;
-		try {
-			channel = openFileChannel(path, forWriting);
-			final FileLock lock = channel.tryLock(0, Long.MAX_VALUE, !forWriting);
-			return lock == null ? null : new ChannelLock(channel, lock);
-		} catch (Exception e) {
-			closeQuietly(channel);
-			throw e;
+			if (policy == IoPolicy.STRICT) {
+				closeQuietly(channel);
+				throw e;
+			} else {
+				return new ChannelLock(channel, null);
+			}
 		}
 	}
 

src/main/java/org/janelia/saalfeldlab/n5/FileKeyLockManager.java

@@ -31,6 +31,7 @@
 import java.io.IOException;
 import java.lang.ref.ReferenceQueue;
 import java.lang.ref.WeakReference;
+import java.nio.channels.FileLock;
 import java.nio.file.Path;
 import java.util.concurrent.ConcurrentHashMap;
 
@@ -79,25 +80,26 @@ private void cleanUp()
 		}
 	}
 
-	private KeyLockState keyLockState(final Path path) {
+	private KeyLockState keyLockState(final Path path, final IoPolicy policy) throws IOException {
 
 		final String key = path.toAbsolutePath().toString();
 
 		cleanUp();
 
 		final WeakValue existingRef = locks.get(key);
 		KeyLockState state = existingRef == null ? null : existingRef.get();
-		if (state != null) {
-			return state;
+		if (state == null) {
+			final KeyLockState newState = new KeyLockState(path, policy);
+			while (state == null) {
+				final WeakValue ref = locks.compute(key,
+						(k, v) -> (v != null && v.get() != null)
+								? v
+								: new WeakValue(k, newState, refQueue));
+				state = ref.get();
+			}
 		}
-
-		final KeyLockState newState = new KeyLockState(path);
-		while (state == null) {
-			final WeakValue ref = locks.compute(key,
-					(k, v) -> (v != null && v.get() != null)
-							? v
-							: new WeakValue(k, newState, refQueue));
-			state = ref.get();
+		if (state.policy() != policy) {
+			throw new IOException("Trying to lock \"" + path + "\" with policy " + policy + ", but it is already used with " + state.policy());
 		}
 		return state;
 	}
@@ -108,31 +110,73 @@ private KeyLockState keyLockState(final Path path) {
 	 * <p>
 	 * The first reader will acquire a shared file lock. Subsequent readers
 	 * only acquire the thread-level lock.
+	 * <p>
+	 * The given locking {@link IoPolicy policy} applies to OS-level locking.
+	 * For both the {@code STRICT} and {@code PERMISSIVE} policy, a {@link
+	 * FileLock} is obtained. If this fails, {@code STRICT} will throw an {@code
+	 * IOException}. {@code PERMISSIVE} will proceed without locking. {@code
+	 * UNSAFE} will not attempt OS-level locking, however will still manage
+	 * mutual exclusion of readers and writers in the same JVM. Trying to lock
+	 * the same path with different locking policies will throw an {@code
+	 * IOException}.
 	 *
 	 * @param path
-	 *            the key (file path) to lock for reading
+	 * 		the key (file path) to lock for reading
+	 * @param policy
+	 * 		the locking policy
+	 *
 	 * @return a {@link LockedChannel} that must be closed when done
+	 *
 	 * @throws IOException
-	 *             if acquiring the file lock fails
+	 * 		if acquiring the file lock fails
+	 */
+	public LockedFileChannel lockForReading(final Path path, final IoPolicy policy) throws IOException {
+
+		return keyLockState(path, policy).acquireRead();
+	}
+
+	/**
+	 * Acquires a read lock for the specified key with the {@link IoPolicy#STRICT} locking policy.
 	 */
 	public LockedFileChannel lockForReading(final Path path) throws IOException {
 
-		return keyLockState(path).acquireRead();
+		return lockForReading(path, IoPolicy.STRICT);
 	}
 
 	/**
 	 * Acquires a write lock for the specified key. Only one thread can hold a
 	 * write lock for a key at a time, and no readers can hold locks.
+	 * <p>
+	 * The given locking {@link IoPolicy policy} applies to OS-level locking.
+	 * For both the {@code STRICT} and {@code PERMISSIVE} policy, a {@link
+	 * FileLock} is obtained. If this fails, {@code STRICT} will throw an {@code
+	 * IOException}. {@code PERMISSIVE} will proceed without locking. {@code
+	 * UNSAFE} will not attempt OS-level locking, however will still manage
+	 * mutual exclusion of readers and writers in the same JVM. Trying to lock
+	 * the same path with different locking policies will throw an {@code
+	 * IOException}.
 	 *
 	 * @param path
-	 *            the file path to lock for writing
+	 * 		the file path to lock for writing
+	 * @param policy
+	 * 		the locking policy
+	 *
 	 * @return a {@link LockedChannel} that must be closed when done
+	 *
 	 * @throws IOException
-	 *             if acquiring the file lock fails
+	 * 		if acquiring the file lock fails
+	 */
+	public LockedFileChannel lockForWriting(final Path path, final IoPolicy policy) throws IOException {
+
+		return keyLockState(path, policy).acquireWrite();
+	}
+
+	/**
+	 * Acquires a write lock for the specified key with the {@link IoPolicy#STRICT} locking policy.
 	 */
 	public LockedFileChannel lockForWriting(final Path path) throws IOException {
 
-		return keyLockState(path).acquireWrite();
+		return lockForWriting(path, IoPolicy.STRICT);
 	}
 
 	/**
@@ -144,14 +188,4 @@ int size() {
 
 		return locks.size();
 	}
-
-	/**
-	 * Removes the lock state for a key if no locks are held.
-	 *
-	 * @param key the key whose lock state should be removed
-	 * @return true if removed, false if currently in use or not found
-	 */
-	public boolean removeLockIfUnused(final String key) {
-		throw new UnsupportedOperationException("TODO. REMOVE");
-	}
 }