[Libguestfs] [PATCH 4/5] threads: Update documentation in guestfs(3) to describe the new behaviour.

[Richard W.M. Jones]

---
 src/guestfs.pod | 33 +++++++++++++++++++++++++--------
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/src/guestfs.pod b/src/guestfs.pod
index e2ee1b5..d7abd79 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -1319,14 +1319,31 @@ encrypted devices.
 All high-level libguestfs actions are synchronous.  If you want
 to use libguestfs asynchronously then you must create a thread.
 
-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.  Even
-apparently innocent functions like L</guestfs_get_trace> are I<not>
-safe to be called from multiple threads without a mutex.
-
-See the graphical program guestfs-browser for one possible
-architecture for multithreaded programs using libvirt and libguestfs.
+=head3 Threads in libguestfs E<ge> 1.30
+
+In libguestfs E<ge> 1.30, each handle (C<guestfs_h>) contains a lock
+which is acquired automatically when you call a libguestfs function.
+The practical effect of this is you can call libguestfs functions with
+the same handle from multiple threads without needing to do any
+locking.
+
+Also in libguestfs E<ge> 1.30, the last error on the handle
+(L</guestfs_last_error>, L</guestfs_last_errno>) is stored in
+thread-local storage, so it is safe to write code like:
+
+ if (guestfs_add_drive_ro (g, drive) == -1)
+   fprintf (stderr, "error was: %s\n", guestfs_last_error (g));
+
+even when other threads may be concurrently using the same handle C<g>.
+
+=head3 Threads in libguestfs E<lt> 1.30
+
+In libguestfs E<lt> 1.30, you must use the handle only 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.  Even apparently innocent functions like
+L</guestfs_get_trace> are I<not> safe to be called from multiple
+threads without a mutex in libguestfs E<lt> 1.30.
 
 =head2 PATH
 
-- 
2.3.1