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

[Richard W.M. Jones]

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

diff --git a/lib/guestfs.pod b/lib/guestfs.pod
index f2a54a1fd..c337345f0 100644
--- a/lib/guestfs.pod
+++ b/lib/guestfs.pod
@@ -1338,14 +1338,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.38
+
+In libguestfs E<ge> 1.38, 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.38, 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.38
+
+In libguestfs E<lt> 1.38, 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.38.
 
 Use L</guestfs_set_identifier> to make it simpler to identify threads
 in trace output.
-- 
2.13.0