|author||Miklos Vajna <firstname.lastname@example.org>||2019-11-22 14:56:56 +0100|
|committer||Miklos Vajna <email@example.com>||2019-11-22 19:41:03 +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 <firstname.lastname@example.org>
1 files changed, 39 insertions, 0 deletions
diff --git a/vcl/README b/vcl/README
index 83c5d044bdd2..e0944688f2f3 100644
@@ -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
+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
+In short, never hold any mutex unless necessary, especially not when calling