This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
Home Products Support Community News


[Xen-API] [PATCH] tidy up some ocamldoc

To: xen-api@xxxxxxxxxxxxxxxxxxx
Subject: [Xen-API] [PATCH] tidy up some ocamldoc
From: David Scott <dave.scott@xxxxxxxxxxxxx>
Date: Tue, 22 Dec 2009 11:37:25 +0000
Delivery-date: Tue, 22 Dec 2009 03:32:25 -0800
Envelope-to: www-data@xxxxxxxxxxxxxxxxxxx
List-help: <mailto:xen-api-request@lists.xensource.com?subject=help>
List-id: Discussion of API issues surrounding Xen <xen-api.lists.xensource.com>
List-post: <mailto:xen-api@lists.xensource.com>
List-subscribe: <http://lists.xensource.com/mailman/listinfo/xen-api>, <mailto:xen-api-request@lists.xensource.com?subject=subscribe>
List-unsubscribe: <http://lists.xensource.com/mailman/listinfo/xen-api>, <mailto:xen-api-request@lists.xensource.com?subject=unsubscribe>
Sender: xen-api-bounces@xxxxxxxxxxxxxxxxxxx
# 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 @@
  * 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 
+    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 
+      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, 
-       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 
1 file changed, 31 insertions(+), 5 deletions(-)
stdext/forkhelpers.mli |   36 +++++++++++++++++++++++++++++++-----

Attachment: xen-api-libs.hg.patch
Description: Text Data

xen-api mailing list
<Prev in Thread] Current Thread [Next in Thread>
  • [Xen-API] [PATCH] tidy up some ocamldoc, David Scott <=