diff options
author | Miklos Vajna <vmiklos@collabora.com> | 2019-11-22 14:56:56 +0100 |
---|---|---|
committer | Miklos Vajna <vmiklos@collabora.com> | 2019-11-22 19:41:03 +0100 |
commit | a0fdbc49e66244d0c43c8b035ff17a0fd62506a3 (patch) | |
tree | a1cc7f1cf3480433adb811dd71a345b6bf51b9bc | |
parent | b4554b8eddd048532269df610e89ae739c46fab7 (diff) |
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@collabora.com>
-rw-r--r-- | vcl/README | 39 |
1 files changed, 39 insertions, 0 deletions
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. |