nasty issue with fcntl locks

doc/todo/fcntl_locks_break_with_threaded_concurrency.mdwn

@@ -0,0 +1,27 @@
+When using git-annex get -J2, one thread can clear another thread's
+transfer lock.
+
+This happens because fcntl locking is used, and it is not thread-safe.
+<https://github.com/haskell/unix/issues/44>
+
+>        *  If a process closes any  file  descriptor  referring  to  a
+>           file,  then  all  of  the  process's locks on that file are
+>           released, regardless of the file descriptor(s) on which the
+>           locks  were obtained. 
+
+One thread starts a transfer and locks it; the second thread starts a
+transfer of a different file, and in order to check annex.diskreserve,
+checks to see which other transfers are currently running. In doing this
+check, it closes a fd attached to the first thread's lock, which causes the
+lock to be dropped.
+
+This only affects -J mode.
+
+To fix it, probably need to use STM to keep a list of transfers all threads
+in the current process are doing. Then the lock checking code can avoid
+re-opening locks for transfers in the STM list.
+
+A more generic approach is to use Annex.LockFile for everything,
+and make it check its lock pool via STM for other threads holding a lock.
+(Currently, the pool is only used for shared locks.)
+--[[Joey]]