From b54cce6cdd9a65a32cdf04ff89cac869eaf2d794 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Fri, 19 Aug 2022 08:29:36 -0400
Subject: [PATCH] mem: Document OOM behavior for allocations

For all the memory allocator APIS, document
that they terminate the program on failure.

This was so far only mentioned in the long description,
and in the docs for g_try_malloc(). And with gi-docgen
style docs, the long description is going away.

(cherry-picked from commit 1df83acb876c8325dfadf96bafc5751e1d9e5447)
---
 glib/gmem.c | 45 +++++++++++++++++++++++++++++++++------------
 1 file changed, 33 insertions(+), 12 deletions(-)

diff --git a/glib/gmem.c b/glib/gmem.c
index 060e91af9..e604d1f71 100644
--- a/glib/gmem.c
+++ b/glib/gmem.c
@@ -109,10 +109,13 @@ static GMemVTable glib_mem_vtable = {
 /**
  * g_malloc:
  * @n_bytes: the number of bytes to allocate
- * 
+ *
  * Allocates @n_bytes bytes of memory.
  * If @n_bytes is 0 it returns %NULL.
- * 
+ *
+ * If the allocation fails (because the system is out of memory),
+ * the program is terminated.
+ *
  * Returns: a pointer to the allocated memory
  */
 gpointer
@@ -139,10 +142,13 @@ g_malloc (gsize n_bytes)
 /**
  * g_malloc0:
  * @n_bytes: the number of bytes to allocate
- * 
+ *
  * Allocates @n_bytes bytes of memory, initialized to 0's.
  * If @n_bytes is 0 it returns %NULL.
- * 
+ *
+ * If the allocation fails (because the system is out of memory),
+ * the program is terminated.
+ *
  * Returns: a pointer to the allocated memory
  */
 gpointer
@@ -170,13 +176,16 @@ g_malloc0 (gsize n_bytes)
  * g_realloc:
  * @mem: (nullable): the memory to reallocate
  * @n_bytes: new size of the memory in bytes
- * 
+ *
  * Reallocates the memory pointed to by @mem, so that it now has space for
  * @n_bytes bytes of memory. It returns the new address of the memory, which may
  * have been moved. @mem may be %NULL, in which case it's considered to
  * have zero-length. @n_bytes may be 0, in which case %NULL will be returned
  * and @mem will be freed unless it is %NULL.
- * 
+ *
+ * If the allocation fails (because the system is out of memory),
+ * the program is terminated.
+ *
  * Returns: the new address of the allocated memory
  */
 gpointer
@@ -343,10 +352,13 @@ g_try_realloc (gpointer mem,
  * g_malloc_n:
  * @n_blocks: the number of blocks to allocate
  * @n_block_bytes: the size of each block in bytes
- * 
+ *
  * This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
  * but care is taken to detect possible overflow during multiplication.
- * 
+ *
+ * If the allocation fails (because the system is out of memory),
+ * the program is terminated.
+ *
  * Since: 2.24
  * Returns: a pointer to the allocated memory
  */
@@ -367,10 +379,13 @@ g_malloc_n (gsize n_blocks,
  * g_malloc0_n:
  * @n_blocks: the number of blocks to allocate
  * @n_block_bytes: the size of each block in bytes
- * 
+ *
  * This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
  * but care is taken to detect possible overflow during multiplication.
- * 
+ *
+ * If the allocation fails (because the system is out of memory),
+ * the program is terminated.
+ *
  * Since: 2.24
  * Returns: a pointer to the allocated memory
  */
@@ -392,10 +407,13 @@ g_malloc0_n (gsize n_blocks,
  * @mem: (nullable): the memory to reallocate
  * @n_blocks: the number of blocks to allocate
  * @n_block_bytes: the size of each block in bytes
- * 
+ *
  * This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
  * but care is taken to detect possible overflow during multiplication.
- * 
+ *
+ * If the allocation fails (because the system is out of memory),
+ * the program is terminated.
+ *
  * Since: 2.24
  * Returns: the new address of the allocated memory
  */
@@ -554,6 +572,9 @@ g_mem_profile (void)
  * alignment value. Additionally, it will detect possible overflow during
  * multiplication.
  *
+ * If the allocation fails (because the system is out of memory),
+ * the program is terminated.
+ *
  * Aligned memory allocations returned by this function can only be
  * freed using g_aligned_free().
  *