Merge branch '2958-thread-pool-docs' into 'main'

gthreadpool: Document that g_thread_pool_new() will spawn a thread

Closes #2958

See merge request GNOME/glib!3412

docs/reference/glib/programming.xml

@@ -19,6 +19,17 @@ General considerations when programming with GLib
 <refsect1>
 <title>Writing GLib Applications</title>
 
+<refsect2>
+<title>Memory Allocations</title>
+
+<para>
+Unless otherwise specified, all functions which allocate memory in GLib will
+abort the process if heap allocation fails. This is because it is too hard to
+recover from allocation failures in any non-trivial program and, in particular,
+to test all the allocation failure code paths.
+</para>
+</refsect2>
+
 <refsect2>
 <title>Threads</title>
 
@@ -34,9 +45,16 @@ GLib creates a worker thread for its own purposes so GLib applications
 will always have at least 2 threads.
 </para>
 
+<para>
+In particular, this means that programs must only use
+<ulink url="man:signal-safety(7)">async-signal-safe functions</ulink> between
+calling <function>fork()</function> and <function>exec()</function>, even if
+they haven’t explicitly spawned another thread yet.
+</para>
+
 <para>
 See the sections on <link linkend="glib-Threads">threads</link> and
-<link linkend="glib-Thread-Pools">threadpools</link> for GLib APIs that
+<link linkend="glib-Thread-Pools">thread pools</link> for GLib APIs that
 support multithreaded applications.
 </para>
 

glib/gthreadpool.c

@@ -536,10 +536,14 @@ g_thread_pool_start_thread (GRealThreadPool  *pool,
  * since their threads are never considered idle and returned to the
  * global pool.
  *
- * Note that the threads used by exclusive threadpools will all inherit the
+ * Note that the threads used by exclusive thread pools will all inherit the
  * scheduler settings of the current thread while the threads used by
- * non-exclusive threadpools will inherit the scheduler settings from the
+ * non-exclusive thread pools will inherit the scheduler settings from the
- * first thread that created such a threadpool.
+ * first thread that created such a thread pool.
+ *
+ * At least one thread will be spawned when this function is called, either to
+ * create the @max_threads exclusive threads, or to preserve the scheduler
+ * settings of the current thread for future spawns.
  *
  * @error can be %NULL to ignore errors, or non-%NULL to report
  * errors. An error can only occur when @exclusive is set to %TRUE