[Libreoffice-commits] core.git: vcl/README

[Miklos Vajna (via logerrit)]

 vcl/README |   39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

New commits:
commit a0fdbc49e66244d0c43c8b035ff17a0fd62506a3
Author:     Miklos Vajna <vmiklos at collabora.com>
AuthorDate: Fri Nov 22 14:56:56 2019 +0100
Commit:     Miklos Vajna <vmiklos at collabora.com>
CommitDate: Fri Nov 22 19:41:03 2019 +0100

    vcl: add brief doc on SolarMutexGuard
    
    Muhammet points out this is not really written down anywhere.
    
    Change-Id: Ied122d9e252e3eff7b088abe95a563dff89e8fff
    Reviewed-on: https://gerrit.libreoffice.org/83490
    Tested-by: Jenkins
    Reviewed-by: Miklos Vajna <vmiklos at collabora.com>

diff --git a/vcl/README b/vcl/README
index 83c5d044bdd2..e0944688f2f3 100644
--- a/vcl/README
+++ b/vcl/README
@@ -201,3 +201,42 @@ To de-compress the contents of a PDF file written by a release build or
 other programs, use the "pdfunzip" tool:
 
 bin/run pdfunzip input.pdf output.pdf
+
+=== SolarMutexGuard ===
+
+The solar mutex is the "big kernel lock" of LibreOffice, a global one. It's a
+recursive mutex, so it's allowed to take the lock on the same thread multiple
+times, and only the last unlock will actually release the mutex.
+
+UNO methods on components can be called from multiple threads, while the
+majority of the codebase is not prepared for multi-threading. One way to get
+around this mismatch is to create a SolarMutexGuard instance at the start of
+each & every UNO method implementation, but only when it is necessary:
+
+- Only acquire the SolarMutex if you actually need it (e.g., not in functions
+  that return static information).
+
+- Only around the code that actually needs it (i.e., never call out with it
+  locked).
+
+This way you ensure that code (not prepared for multithreading) is still
+executed only on a single thread.
+
+In case you expect that your caller takes the solar mutex, then you can use
+the DBG_TESTSOLARMUTEX() macro to assert that in dbgutil builds.
+
+Event listeners are a special (but frequent) case of the "never call out with
+a mutex (SolarMutex or other) locked" fundamental rule:
+
+- UNO methods can be called from multiple threads, so most implementations
+  take the solar mutex as their first action when necessary.
+
+- This can be problematic if later calling out (an event handler is called),
+  where the called function may be an UNO method implementation as well and
+  may be invoked on a different thread.
+
+- So we try to not own the solar mutex, whenever we call out (invoke event
+  listeners).
+
+In short, never hold any mutex unless necessary, especially not when calling
+out.