# 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
1 file changed, 31 insertions(+), 5 deletions(-)
stdext/forkhelpers.mli | 36 +++++++++++++++++++++++++++++++-----
xen-api-libs.hg.patch
Description: Text Data
_______________________________________________
xen-api mailing list
xen-api@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/mailman/listinfo/xen-api
|
Home