docs of g_main_context_prepare does not mention g_main_context_acquire
Submitted by Jarek Czekalski
Link to original bug (#719756)
Description
Please add notes about g_main_context_acquire to the following functions:
g_main_context_prepare() g_main_context_query() g_main_context_check() g_main_context_dispatch()
The required note is something like that:
Owning the context, for example through g_main_context_acquire(), is necessary before calling this function.
I found this information in the docs of g_main_context_acquire, but the usual workflow is probably as follows:
- One reads "Customizing the main loop iteration" chapter (with a nice diagram!)
- Then reads documentation of the 4 functions mentioned above
- Starts coding their customized main loop
This results in missing and not obeying the rule presented in g_main_context_acquire. If the rule is correct, please make it obvious to the potential users of the 4 functions.
I report this bug because I see the _query method called without _acquire in a very popular gnu package. Something wrong is happening there, maybe due to not acquiring the context.
[1] https://developer.gnome.org/glib/2.37/glib-The-Main-Event-Loop.html#id-1.4.2.4.9.2
Version: 2.37.x