guestfs: Reference guestfs-browser architecture in threads documentation.

[libguestfs.git] / src / guestfs.pod

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 24d5aef..de5e254 100644 (file)
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -43,7 +43,7 @@ FUSE.
 
 Libguestfs is a library that can be linked with C and C++ management
 programs (or management programs written in OCaml, Perl, Python, Ruby,
 
 Libguestfs is a library that can be linked with C and C++ management
 programs (or management programs written in OCaml, Perl, Python, Ruby,

-Java, Haskell or C#).  You can also use it from shell scripts or the
+Java, PHP, Haskell or C#).  You can also use it from shell scripts or the

 command line.
 
 You don't need to be root to use libguestfs, although obviously you do
 command line.
 
 You don't need to be root to use libguestfs, although obviously you do


@@ -334,7 +334,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.
 


@@ -626,6 +626,13 @@ For documentation see the file C<guestfs.mli>.
 
 For documentation see L<Sys::Guestfs(3)>.
 
 
 For documentation see L<Sys::Guestfs(3)>.
 

+=item B<PHP>
+
+For documentation see C<README-PHP> supplied with libguestfs
+sources or in the php-libguestfs package for your distribution.
+
+The PHP binding only works correctly on 64 bit machines.
+

 =item B<Python>
 
 For documentation do:
 =item B<Python>
 
 For documentation do:


@@ -1102,24 +1109,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
 


@@ -1518,10 +1522,23 @@ 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.
+
+=head3 PROGRESS NOTIFICATION MESSAGES
+
+The daemon may send progress notification messages at any time.  These
+are distinguished by the normal length word being replaced by
+C<GUESTFS_PROGRESS_FLAG>, followed by a fixed size progress message.
+
+The library turns them into progress callbacks (see
+C<guestfs_set_progress_callback>) if there is a callback registered,
+or discards them if not.
+
+The daemon self-limits the frequency of progress messages it sends
+(see C<daemon/proto.c:notify_progress>).  Not all calls generate
+progress messages.

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


@@ -1532,6 +1549,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