doc: add some recommendations around slow HDDs

grok-pull is still painful with serialization on an old USB 2.0
HDD, but at least it can finish with flock(1) and disabling
parallelization.  While parallel "git fetch" doesn't seem so
bad, slow seeks are exacerbated by parallel reads in Xapian.
That means some updates can take days instead of hours.  The
same updates take only seconds or minutes on an SSD.

diff --git a/Documentation/public-inbox-index.pod b/Documentation/public-inbox-index.pod
index b1b24917bbb65814700c20b7dde2307eca30ca75..ff2e5486748889667667de1ef0f86d0d6f390115 100644 (file)
--- a/Documentation/public-inbox-index.pod
+++ b/Documentation/public-inbox-index.pod
@@ -32,6 +32,16 @@ normal search functionality.
 
 =over
 
+=item --jobs=JOBS, -j
+
+Control the number of Xapian indexing jobs in a
+(L<public-inbox-v2-format(5)>) inbox.
+
+C<--jobs=0> is accepted as of public-inbox 1.6.0 (PENDING)
+to disable parallel indexing.
+
+Default: the number of existing Xapian shards
+
 =item --compact / -c
 
 Compacts the Xapian DBs after indexing.  This is recommended

diff --git a/examples/grok-pull.post_update_hook.sh b/examples/grok-pull.post_update_hook.sh
index 3ead394408eb68f80950f78b6326f2ee5e1f471c..ec4ae93e829dc93eee66b3dbfc4a58bd28c49e4b 100755 (executable)
--- a/examples/grok-pull.post_update_hook.sh
+++ b/examples/grok-pull.post_update_hook.sh
@@ -1,4 +1,9 @@
 #!/bin/sh
+
+# use flock(1) from util-linux to avoid seek contention on slow HDDs
+# when using multiple `pull_threads' with grok-pull:
+# [ "${FLOCKER}" != "$0" ] && exec env FLOCKER="$0" flock "$0" "$0" "$@" || :
+
 # post_update_hook for repos.conf as used by grok-pull, takes a full
 # git repo path as it's first and only arg.
 full_git_dir="$1"
@@ -119,6 +124,7 @@ then
                : v2 inboxes may be init-ed with an empty msgmap
                ;;
        *)
+               # if on HDD and limited RAM, add `-j0' w/ public-inbox 1.6.0+
                $EATMYDATA public-inbox-index -v "$inbox_dir"
                ;;
        esac