Re: Clarification of GTK/GDK locking pre GTK 4.0

[Yehouda Harpaz <yeh lispworks com>]

[ previou ssent too early. some minor inprovements]

Below is my description of GTK threading that try to clarify the issue.

Apart from comments about the contents, also need comments about
the language and how clear it is, and also where this should go.

I ignore Windows, I don't know how it is supposed to work on Windows.

========================================
========================================


GTK threading: GTK2/3 vs GTK4

GTK (which here includes GDK) is not thread-safe, and GTK users
must ensure that GTK operations are not done in parallel. That is
done differently in GTK2/3 and GTK4:

1) In GTK2/3 GTK operations must be done while holding the 
   GDK lock. 
2) In GTK4 GTK operations must be done on the "main thread", which
   is the thread where g_main_loop_run runs, and hence all events are processed.

===============================
GTK2/3 model: with the GDK lock held. 
-------------------------------

In GTK2/3 GTK calls must be done while holding the GDK lock. This is
manadatory for components (libraries). Standalone applications can get
away with using the GTK4 model.

A piece of code is executed with the GDK lock held in three situations: 

1) It is executed in the scope of "GTK code", which must be holding the GDK
   lock. That include all GTK signals and notifications, and any code that 
   access GTK objects. That is a very common situation.

   Note that this does NOT include code that is invoked by the G scheduling
   functions (g_idle_add, g_idle_add_full, g_timeut_add, g_timeout_add_full).
   For these, the callbacks that they take is NOT called in the context in which
   the sceduling function was called, and the callback is always called WITHOUT
   the GDK lock. Other G functions like g_main_context_invoke and using g_source
   explicitly have have more complex behaviour. All of these function
   must NOT be used to schedule callbacks that may call GTK functions. 


2) The code is scheduled using the GDK scheduling functions (gdk_threads_add_*). As
   opposed to the G scheduling functions above, the callbacks of GDK scheduling
   functions are always called with the GDK lock held (on GTK2/3). That is totally
   independent of where the GDK scheduling function itelf was called.


3) The code is inside exelicit GDK locking, i.e. between a pair of calls to 
   gdk_threads_enter and gdk_threads_leave. 

===============================
Comaptibility with GTK4:
-------------------------------
1) Code that is called inside the scope of "GTK code" will still not need to do anything,
   because the "GTK code" will be executed only on the main thread.
2) Callbacks setup by the GDK scheduling function will still be ok, because they 
   are always invoked on the main thread. In GTK4, it will happen without
   the lock. 
3) Code that uses explicit lock is NOT going to work, and will have to change
   to do any GTK operations on the main thread.

===============================
Standalone applications on GTK2/3
----------------------------------
Components for GTK2/3 must adhere to the rules above. Standalone application
can get away by using the GTK4 model of running all GTK operations on the main 
thread. 

This relies on the assumption that all components that are used,
either internally by GTK or explicitly by the application, are "well
behaved", which means that they perform GTK operation either on
the thread on which  their interface functions are invoked or
on the main thread. This assumption is probably true for modules that GTK
loads internally, but strictly speaking is not a requirement in GTK2/3.

===============================
GTK4 model: on the main thread
-------------------------------
On GTK4, all GTK operations must be done on the main thread. 

When code that executes on another thread needs to execute GTK
operations, it must do it on the main thread, by scheduling some
callback. This can be done by any of the G scheduling functions or the
GDK scheduling (which on GTK4 will do the same thing as the G
scheduling functions).