854
'test_done'.
855
856
857
+Writing concurrency-safe helpers
858
+--------------------------------
859
+
860
+Some test code runs concurrently: a test may background work with '&',
861
+and the helper scripts installed for the web server (in t/lib-httpd) are
862
+run once per request, so the same script can execute for several
863
+requests at once. Such code cannot assume it has exclusive access to a
864
+file.
865
+
866
+When exactly one of several concurrent processes needs to "win" a
867
+decision, a single atomic filesystem operation can make it, rather than
868
+a check followed by a separate action. A "test -f X" then "touch X"
869
+(or "rm X") races: two processes can both pass the check before either
870
+acts. Two atomic operations avoid this:
871
+
872
+ - "mkdir dir", which fails if the directory already exists, so that
873
+ exactly one caller wins, electing a first or only request (see
874
+ t/lib-httpd/http-429.sh).
875
+
876
+ - "mv src dst" (rename), which fails if the source is gone, so that
877
+ exactly one caller consumes it, claiming a planted one-shot marker
878
+ (see t/lib-httpd/apply-one-time-script.sh).
879
+
880
+A "$$" suffix on per-request scratch files keeps concurrent invocations
881
+from clobbering each other's fixed-name files.
882
+
883
+This is a standard shell locking idiom, and the same reasoning behind
884
+Git's own lockfile machinery, which creates its lock with O_CREAT|O_EXCL,
885
+and make_symlink() in t/test-lib.sh, which uses an mkdir lock: an atomic
886
+operation whose failure indicates that another process got there first.
887
+
888
+
889
Test harness library
890
--------------------
891