commit 0a94e1584ecb9244495ad1001f5475bc49041a70
author Elliott Hughes <enh@google.com> Mon Jun 26 19:03:41 2023 +0000
committer Elliott Hughes <enh@google.com> Mon Jun 26 19:03:41 2023 +0000
tree 9377529d01131071386dd43dc61360b79976b801
parent 48d405ea4b06f7ebde5ac2a372c9ad90c7ac012e

Explicitly document overcommit and `adb shell`'s use of oom_score_adj.

This comes up now and then, and the different behavior with `adb shell`
in particular confuses people.

Bug: https://github.com/android/ndk/issues/1897
Test: N/A
Change-Id: I757fa6b6277610a139f326563d508fb9009dcb75

libc/include/malloc.h

diff --git a/libc/include/malloc.h b/libc/include/malloc.h
index 6cd8509..6f992d9 100644
--- a/libc/include/malloc.h
+++ b/libc/include/malloc.h
@@ -39,6 +39,21 @@
  *
  * Returns a pointer to the allocated memory on success and returns a null
  * pointer and sets `errno` on failure.
+ *
+ * Note that Android (like most Unix systems) allows "overcommit". This
+ * allows processes to allocate more memory than the system has, provided
+ * they don't use it all. This works because only "dirty" pages that have
+ * been written to actually require physical memory. In practice, this
+ * means that it's rare to see memory allocation functions return a null
+ * pointer, and that a non-null pointer does not mean that you actually
+ * have all of the memory you asked for.
+ *
+ * Note also that the Linux Out Of Memory (OOM) killer behaves differently
+ * for code run via `adb shell`. The assumption is that if you ran
+ * something via `adb shell` you're a developer who actually wants the
+ * device to do what you're asking it to do _even if_ that means killing
+ * other processes. Obviously this is not the case for apps, which will
+ * be killed in preference to killing other processes.
  */
 void* _Nullable malloc(size_t __byte_count) __mallocfunc __BIONIC_ALLOC_SIZE(1) __wur;
 
@@ -47,7 +62,7 @@
  * and clears memory on the heap.
  *
  * Returns a pointer to the allocated memory on success and returns a null
- * pointer and sets `errno` on failure.
+ * pointer and sets `errno` on failure (but see the notes for malloc()).
  */
 void* _Nullable calloc(size_t __item_count, size_t __item_size) __mallocfunc __BIONIC_ALLOC_SIZE(1,2) __wur;
 
@@ -56,7 +71,8 @@
  * allocated memory on the heap.
  *
  * Returns a pointer (which may be different from `__ptr`) to the resized
- * memory on success and returns a null pointer and sets `errno` on failure.
+ * memory on success and returns a null pointer and sets `errno` on failure
+ * (but see the notes for malloc()).
  */
 void* _Nullable realloc(void* _Nullable __ptr, size_t __byte_count) __BIONIC_ALLOC_SIZE(2) __wur;
 
@@ -68,7 +84,8 @@
  * multiplication overflows.
  *
  * Returns a pointer (which may be different from `__ptr`) to the resized
- * memory on success and returns a null pointer and sets `errno` on failure.
+ * memory on success and returns a null pointer and sets `errno` on failure
+ * (but see the notes for malloc()).
  */
 void* _Nullable reallocarray(void* _Nullable __ptr, size_t __item_count, size_t __item_size) __BIONIC_ALLOC_SIZE(2, 3) __wur __INTRODUCED_IN(29);
 
@@ -83,7 +100,7 @@
  * memory on the heap with the required alignment.
  *
  * Returns a pointer to the allocated memory on success and returns a null
- * pointer and sets `errno` on failure.
+ * pointer and sets `errno` on failure (but see the notes for malloc()).
  *
  * See also posix_memalign().
  */