guestfs: Reference guestfs-browser architecture in threads documentation.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 96b4623..2d30e34 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -331,7 +331,7 @@ files.
 
 =head2 RUNNING COMMANDS
 
 
 =head2 RUNNING COMMANDS
 

-Although libguestfs is a primarily an API for manipulating files
+Although libguestfs is primarily an API for manipulating files

 inside guest images, we also provide some limited facilities for
 running commands inside guests.
 
 inside guest images, we also provide some limited facilities for
 running commands inside guests.
 


@@ -716,11 +716,11 @@ largest number of results.
 =head2 guestfs_set_error_handler
 
  typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
 =head2 guestfs_set_error_handler
 
  typedef void (*guestfs_error_handler_cb) (guestfs_h *g,

-                                           void *data,
+                                           void *opaque,

                                            const char *msg);
  void guestfs_set_error_handler (guestfs_h *g,
                                  guestfs_error_handler_cb cb,
                                            const char *msg);
  void guestfs_set_error_handler (guestfs_h *g,
                                  guestfs_error_handler_cb cb,

-                                 void *data);
+                                 void *opaque);

 
 The callback C<cb> will be called if there is an error.  The
 parameters passed to the callback are an opaque data pointer and the
 
 The callback C<cb> will be called if there is an error.  The
 parameters passed to the callback are an opaque data pointer and the


@@ -737,7 +737,7 @@ If you set C<cb> to C<NULL> then I<no> handler is called.
 =head2 guestfs_get_error_handler
 
  guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
 =head2 guestfs_get_error_handler
 
  guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,

-                                                     void **data_rtn);
+                                                     void **opaque_rtn);

 
 Returns the current error handler callback.
 
 
 Returns the current error handler callback.
 


@@ -962,24 +962,21 @@ causes the state to transition back to CONFIG.
 Configuration commands for qemu such as L</guestfs_add_drive> can only
 be issued when in the CONFIG state.
 
 Configuration commands for qemu such as L</guestfs_add_drive> can only
 be issued when in the CONFIG state.
 

-The high-level API offers two calls that go from CONFIG through
-LAUNCHING to READY.  L</guestfs_launch> blocks until the child process
-is READY to accept commands (or until some failure or timeout).
+The API offers one call that goes from CONFIG through LAUNCHING to
+READY.  L</guestfs_launch> blocks until the child process is READY to
+accept commands (or until some failure or timeout).

 L</guestfs_launch> internally moves the state from CONFIG to LAUNCHING
 while it is running.
 
 L</guestfs_launch> internally moves the state from CONFIG to LAUNCHING
 while it is running.
 

-High-level API actions such as L</guestfs_mount> can only be issued
-when in the READY state.  These high-level API calls block waiting for
-the command to be carried out (ie. the state to transition to BUSY and
-then back to READY).  But using the low-level event API, you get
-non-blocking versions.  (But you can still only carry out one
-operation per handle at a time - that is a limitation of the
-communications protocol we use).
+API actions such as L</guestfs_mount> can only be issued when in the
+READY state.  These API calls block waiting for the command to be
+carried out (ie. the state to transition to BUSY and then back to
+READY).  There are no non-blocking versions, and no way to issue more
+than one command per handle at the same time.

 
 Finally, the child process sends asynchronous messages back to the
 
 Finally, the child process sends asynchronous messages back to the

-main program, such as kernel log messages.  Mostly these are ignored
-by the high-level API, but using the low-level event API you can
-register to receive these messages.
+main program, such as kernel log messages.  You can register a
+callback to receive these messages.

 
 =head2 SETTING CALLBACKS TO HANDLE EVENTS
 
 
 =head2 SETTING CALLBACKS TO HANDLE EVENTS
 


@@ -1272,10 +1269,9 @@ parameters, but with the roles of daemon and library reversed.
 
 =head3 INITIAL MESSAGE
 
 
 =head3 INITIAL MESSAGE
 

-Because the underlying channel (QEmu -net channel) doesn't have any
-sort of connection control, when the daemon launches it sends an
-initial word (C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest
-and daemon is alive.  This is what L</guestfs_launch> waits for.
+When the daemon launches it sends an initial word
+(C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest and daemon is
+alive.  This is what L</guestfs_launch> waits for.

 
 =head1 MULTIPLE HANDLES AND MULTIPLE THREADS
 
 
 =head1 MULTIPLE HANDLES AND MULTIPLE THREADS
 


@@ -1286,6 +1282,9 @@ Only use the handle from a single thread.  Either use the handle
 exclusively from one thread, or provide your own mutex so that two
 threads cannot issue calls on the same handle at the same time.
 
 exclusively from one thread, or provide your own mutex so that two
 threads cannot issue calls on the same handle at the same time.
 

+See the graphical program guestfs-browser for one possible
+architecture for multithreaded programs using libvirt and libguestfs.
+

 =head1 QEMU WRAPPERS
 
 If you want to compile your own qemu, run qemu from a non-standard
 =head1 QEMU WRAPPERS
 
 If you want to compile your own qemu, run qemu from a non-standard