# HG changeset patch
# User David Scott <dave.scott@xxxxxxxxxxxxx>
# Date 1261409810 0
# Node ID 65c971f2b0871ac424a11b3ab1889d45ddeb18f9
# Parent  6927e5e50d612ba1ff5dd33ad3eef0a494afc0fe
CA-33440: add ocamldoc to forkhelpers.mli

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

diff -r 6927e5e50d61 -r 65c971f2b087 stdext/forkhelpers.mli
--- a/stdext/forkhelpers.mli	Mon Dec 21 15:36:49 2009 +0000
+++ b/stdext/forkhelpers.mli	Mon Dec 21 15:36:50 2009 +0000
@@ -14,25 +14,47 @@
 (* Functions to safely fork potentially long-running sub-processes without
    leaking file descriptors or accidentally deadlocking the parent process. *)
 
-(* Functions should:
-   1. Arrange to close all fds except the ones they actually want to keep open
-   2. Not access any ocaml library or runtime function which might touch a lock
-   (since that would cause deadlock) *)
+(** [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)]
+*)
+val execute_command_get_output : ?cb_set:(int -> unit) -> ?cb_clear:(unit -> unit) -> string -> string list -> string * string
 
-(** Standalone wrapper process which safely closes fds before exec()ing another program.
-	Needs the binary /opt/xensource/libexec/closeandexec installed by close-and-exec. *)
-
-exception Subprocess_failed of int
-exception Subprocess_killed of int
+(** 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
 
+(** Represents a forked process *)
 type pidty
 
+(** [string_of_pidty p] returns a printable string description of [p] *)
 val string_of_pidty : pidty -> string
 
-(** Safe function which forks a command, closing all fds except a whitelist and
-    having performed some fd operations in the child *)
+(** [getpid p] returns the integer process id *)
+val getpid : pidty -> int
+
+(** 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
+
+(** [safe_close_and_exec stdin stdout stderr id_to_fd_list cmd args] runs [cmd args]
+	with the optional [stdin], [stdout] and [stderr] file descriptors (or /dev/null if not
+	specified) and with any key from [id_to_fd_list] in [args] replaced by the integer
+	value of the file descriptor in the final process. *)
 val safe_close_and_exec : ?env:string array -> Unix.file_descr option -> Unix.file_descr option -> Unix.file_descr option -> (string * Unix.file_descr) list -> string -> string list -> pidty
+
+(** [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
+
 
 type 'a result = Success of string * 'a | Failure of string * exn
 
@@ -41,14 +63,5 @@
     function 'f' throws an error then the log file contents are read in *)
 val with_logfile_fd : ?delete:bool -> string -> (Unix.file_descr -> 'a) -> 'a result
 
-(*val with_dev_null : (Unix.file_descr -> 'a) -> 'a
-val with_dev_null_read : (Unix.file_descr -> 'a) -> 'a*)
 
-(** Execute a command, return the stdout logging or throw a Spawn_internal_error exception *)
-val execute_command_get_output : ?cb_set:(int -> unit) -> ?cb_clear:(unit -> unit) -> string -> string list -> string * string
 
-val waitpid : pidty -> (int * Unix.process_status)
-val waitpid_nohang : pidty -> (int * Unix.process_status)
-val dontwaitpid : pidty -> unit
-val waitpid_fail_if_bad_exit : pidty -> unit
-val getpid : pidty -> int