# HG changeset patch
# User David Scott <dave.scott@xxxxxxxxxxxxx>
# Date 1261481820 0
# Node ID 7e4670b5a046dd914812272b81f9d8be55e5aa00
# Parent  1d0215b3b44d0d29c347ab923b1a3a6d2cbb0bb9
[ocamldoc]: attempt to tidy-up the ocamldoc comments in the forkhelpers module

Signed-off-by: David Scott <dave.scott@xxxxxxxxxxxxx>

diff -r 1d0215b3b44d -r 7e4670b5a046 stdext/forkhelpers.mli
--- a/stdext/forkhelpers.mli	Mon Dec 21 21:34:31 2009 +0000
+++ b/stdext/forkhelpers.mli	Tue Dec 22 11:37:00 2009 +0000
@@ -11,16 +11,38 @@
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU Lesser General Public License for more details.
  *)
-(* Functions to safely fork potentially long-running sub-processes without
-   leaking file descriptors or accidentally deadlocking the parent process. *)
+
+(** Functions to execute processes, pass file descriptors around and return results *)
+
+(** The low-level Unix.fork(), Unix.exec*() functions and friends are not safe to 
+    call in multithreaded programs for two reasons:
+    + parallel threads opening new file descriptors will have these descriptors captured
+      by a fork(). This leads to annoying glitches like (for example) attempts to 'umount'
+      a filesystem being rejected because a file is still open.
+    + although Unix.fork() will call (via the ocaml runtime) a pthread_atfork handler
+      which attempts to clean up the state of the threading system in the child, this relies
+      on quite a complex glibc implementation.
+
+    Additionally Unix.fork(), Unix.exec*() are very low-level primitives. When we call
+    these functions what we actually want to do is run some separate process with certain
+    file-descriptors, optionally returning results. 
+
+	The interface in this module
+    + is higher-level than Unix.fork(), Unix.exec*()
+    + allows us to offload Unix.fork(), Unix.exec*() to a single-threaded separate process
+      where the glibc+ocaml runtime codepaths are simpler and hopefully more reliable. *)
+
+(** { 1 High-level interface } *)
 
 (** [execute_command_get_output cmd args] runs [cmd args] and returns (stdout, stderr)
-	on success (exit 0). On failure this raises [Spawn_internal_error(stderr, stdout, Unix.process_status)]
-*)
+	on success (exit 0). On failure this raises 
+    [Spawn_internal_error(stderr, stdout, Unix.process_status)] *)
 val execute_command_get_output : ?env:string array -> string -> string list -> string * string
 
 (** Thrown by [execute_command_get_output] if the subprocess exits with a non-zero exit code *)
 exception Spawn_internal_error of string * string * Unix.process_status
+
+(** { 2 Low-level interface } *)
 
 (** Represents a forked process *)
 type pidty
@@ -33,6 +55,7 @@
 
 (** Thrown by [safe_close_and_exec] if the process exits with a non-zero exit code. *)
 exception Subprocess_failed of int
+
 (** Thrown by [safe_close_and_exec] if the process exits due to a signal *)
 exception Subprocess_killed of int
 
@@ -44,18 +67,21 @@
 
 (** [waitpid p] returns the (pid, Unix.process_status) *)
 val waitpid : pidty -> (int * Unix.process_status)
+
 (** [waitpid_nohang p] returns the (pid, Unix.process_status) if the process has already
 	quit or (0, Unix.WEXITTED 0) if the process is still running. *)
 val waitpid_nohang : pidty -> (int * Unix.process_status)
+
 (** [dontwaitpid p]: signals the caller's desire to never call waitpid. Note that the final
 	process will not persist as a zombie. *)
 val dontwaitpid : pidty -> unit
+
 (** [waitpid_fail_if_bad_exit p] calls waitpid on [p] and throws [Subprocess_failed x] if the 
 	process exits with non-zero code x and [Subprocess_killed x] if the process is killed by a 
 	signal and exits with non-zero code x. *)
 val waitpid_fail_if_bad_exit : pidty -> unit
 
-
+(** result returned by [with_logfile_fd] *)
 type 'a result = Success of string * 'a | Failure of string * exn
 
 (** Creates a temporary file and opens it for logging. The fd is passed to the function