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

2 files changed, 26 insertions, 4 deletions

diff --git a/docs/reference/glib/programming.xml b/docs/reference/glib/programming.xml
index 52df907e8..a952ca3b3 100644
--- a/docs/reference/glib/programming.xml
+++ b/docs/reference/glib/programming.xml
@@ -20,6 +20,17 @@ General considerations when programming with GLib
 <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>
 
 <para>
@@ -35,8 +46,15 @@ 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>
 
diff --git a/glib/gthreadpool.c b/glib/gthreadpool.c
index 54e49b3c0..c18de89d0 100644
--- a/glib/gthreadpool.c
+++ b/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
- * first thread that created such a threadpool.
+ * non-exclusive thread pools will inherit the scheduler settings from the
+ * 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