some notes about COM threading in LO generally and winaccessibility

- document general COM threading architecture in vcl README
- document winaccessiblitiy locking in README
- define _ATL_APARTMENT_THREADED for UAccCOM

Change-Id: I7c3fd952f2cdee7d245a818bf33c477e7ea20fc2

5 files changed, 29 insertions, 5 deletions

diff --git a/sal/osl/w32/thread.c b/sal/osl/w32/thread.c
index 0bb71722694f..a5cf7155e408 100644
--- a/sal/osl/w32/thread.c
+++ b/sal/osl/w32/thread.c
@@ -49,9 +49,8 @@ static unsigned __stdcall oslWorkerWrapperFunction(void* pData)
 {
     osl_TThreadImpl* pThreadImpl= (osl_TThreadImpl*)pData;
 
-    /* Initialize COM */
-
-    CoInitializeEx(NULL, COINIT_MULTITHREADED);
+    /* Initialize COM - Multi Threaded Apartment (MTA) for all threads */
+    CoInitializeEx(0, COINIT_MULTITHREADED); /* spawned by oslCreateThread */
 
     /* call worker-function with data */
 
diff --git a/vcl/README b/vcl/README
index bebb9e1787bf..e4cc92245014 100644
--- a/vcl/README
+++ b/vcl/README
@@ -64,6 +64,13 @@ portable C++ class library for GUIs, with very old roots, that was
 developed by StarDivision. Nowadays it is not used by anything except
 LibreOffice (and OpenOffice).
 
+== COM threading ==
+
+The way COM is used in LO generally:
+- vcl InitSalData() puts main thread into Single-threaded Apartment (STA)
+- oslWorkerWrapperFunction() puts every thread spawned via oslCreateThread()
+  into MTA (free-threaded)
+
 == EMF+ ==
 
 emf+ is vector file format used by MSO and is successor of wmf and
diff --git a/vcl/win/source/app/salinst.cxx b/vcl/win/source/app/salinst.cxx
index 1c5e7e74a8d8..316c5443df95 100644
--- a/vcl/win/source/app/salinst.cxx
+++ b/vcl/win/source/app/salinst.cxx
@@ -446,7 +446,7 @@ SalData::~SalData()
 void InitSalData()
 {
     SalData* pSalData = new SalData;
-    CoInitialize(0);
+    CoInitialize(0); // put main thread in Single Threaded Apartment (STA)
 
     // init GDIPlus
     static Gdiplus::GdiplusStartupInput gdiplusStartupInput;
diff --git a/winaccessibility/README b/winaccessibility/README
index eb425e419b75..bac3681e720a 100644
--- a/winaccessibility/README
+++ b/winaccessibility/README
@@ -26,6 +26,22 @@ Here is one way of visualising the code / control flow
 VCL <-> UNO toolkit <-> UNO a11y <-> win a11y <-> COM / IAccessible2
 vcl/ <-> toolkit/ <-> accessibility/ <-> winaccessibility/ <-> UAccCom/
 
+Threading
+
+It's possible that the UNO components are called from threads other
+than the main thread, so they have to be synchronized. It would be nice
+to put the component into an UNO apartment (and the COM components into STA)
+but UNO would spawn a new thread for it so it's not possible.
+The COM components also call into the same global AccObjectWinManager
+as the UNO components do so both have to be synchronized in the same way.
+So we use the SolarMutex for all synchronization since anything else
+would be rather difficult to make work.  Unfortunately there is a
+pre-exising problem in vcl with Win32 Window creation and destruction
+on non-main threads where a synchronous SendMessage is used while
+the SolarMutex is locked that can cause deadlocks if the main thread is
+waiting on the SolarMutex itself at that time and thus not handing the
+Win32 message; this is easy to trigger with JunitTests but hopefully
+not by actual end users.
 
 Debugging / playing with winaccessibility
 
diff --git a/winaccessibility/source/UAccCOM/stdafx.h b/winaccessibility/source/UAccCOM/stdafx.h
index 66019e2f043a..e71ac0b0a506 100644
--- a/winaccessibility/source/UAccCOM/stdafx.h
+++ b/winaccessibility/source/UAccCOM/stdafx.h
@@ -28,7 +28,9 @@
 #pragma once
 #endif // _MSC_VER > 1000
 
-//#define _ATL_APARTMENT_THREADED
+// this turns off ATL's locking in the COM component implementations
+// (we don't need it since we use SolarMutex instead)
+#define _ATL_APARTMENT_THREADED
 
 #include <prewin.h>
 #include <windows.h>