From: Ken Hornstein <kenh@pobox.com>
Date: Thu, 21 Mar 2013 21:12:42 +0000 (-0400)
Subject: More documentation about locking changes.
X-Git-Url: https://diplodocus.org/git/nmh/commitdiff_plain/85bb87a28dff30d9e90ec80ab33cd97a3f07cb9d?ds=sidebyside;hp=--cc

More documentation about locking changes.
---

85bb87a28dff30d9e90ec80ab33cd97a3f07cb9d
diff --git a/docs/pending-release-notes b/docs/pending-release-notes
index 94a62af3..3ff8fbd9 100644
--- a/docs/pending-release-notes
+++ b/docs/pending-release-notes
@@ -44,6 +44,7 @@ NEW FEATURES
 - A new program, fmttest(1) is included to help debug format files
 - mhshow/mhstore now have support for RFC-2017 (access-type=url) for
   external message bodies.
+- All nmh commands now support transactional locking for sequence files.
 
 ----------------------------
 OBSOLETE/DEPRECATED FEATURES
diff --git a/man/mh-profile.man b/man/mh-profile.man
index 38dafb80..75bea09d 100644
--- a/man/mh-profile.man
+++ b/man/mh-profile.man
@@ -204,7 +204,10 @@ any one of the following entries:
 .RE
 .PP
 Available locking algorithms can vary depending on what is supported by
-the operating system.
+the operating system.  Note: currently transactional locking is only
+supported on public sequences; see
+.IR mh\-sequence (5)
+for more information.
 (profile, default: fcntl)
 .RE
 .PP
diff --git a/man/mh-sequence.man b/man/mh-sequence.man
index f48f80d6..c47b02b7 100644
--- a/man/mh-sequence.man
+++ b/man/mh-sequence.man
@@ -254,6 +254,36 @@ or
 displays a message, that message will be removed from
 any sequences named by the \*(lqUnseen\-Sequence\*(rq entry in the
 profile.
+.SS Sequence File Locking
+The \*(lqdatalocking\*(rq profile entry controls the type of locking used
+when reading and writing sequence files.  The locking mechanisms supported
+are detailed in
+.IR mh\-profile (5).
+This protects sequence file integrity when multiple
+.B nmh
+commands are run simultaneously.
+.B Nmh
+commands that modify the sequence file use transactional locks; the lock
+is held from the time the sequence file is read until it it written out.
+This ensures that modifications to the sequence file will not be lost
+if multiple commands are run simultaneously.  Long\-running
+.B nmh
+commands, such as
+.B inc
+and
+.BR pick ,
+will release the sequence lock during the bulk of their runtime and reread
+the sequence file after their processing is complete to reduce lock
+contention time.
+.PP
+.B Note:
+Currently transactional locks are
+.B only
+supported for public sequences; private sequences will not get corrupted, but
+the possibility exists that two
+.B nmh
+commands run simultaneously that add messages to a private sequence could result in
+one command's messages not appearing on the requested sequence.
 .SH FILES
 .fc ^ ~
 .nf