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

--- src/guestfs.pod | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/src/guestfs.pod b/src/guestfs.pod index 5ceef92..2384a1d 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