Mozilla 2/Memory/OOM API

Rationale

Memory allocation is an integral part of any non-trivial application, and in principle any allocation can fail due to being Out Of Memory (OOM). The traditional approach to OOM handling is to check for failure at every allocation point in the application and execute recovery code. Unfortunately, such recovery can be quite complex, depending on the surrounding code. Even worse, actual OOM conditions are rare, so the recovery code is very difficult to adequately test.

We need to improve our OOM handling approach so that it is possible to reliably and efficiently run with constrained memory resources. This is particularly important when running on mobile platforms.

Standard can-fail API

The standard memory allocation functions can fail due to an OOM condition. If failure occurs, each function sets the return value accordingly, and it is up to the caller to deal appropriately with the error.

void *malloc(size_t size);
void *valloc(size_t size); /* Legacy compatibility function. */
void *calloc(size_t num, size_t size);
void *realloc(void *ptr, size_t size);
int posix_memalign(void **memptr, size_t alignment, size_t size);
void *memalign(size_t alignment, size_t size);

New no-fail API

The no-fail functions will either succeed or terminate the application before returning. See later sections for related information on internal mechanisms that are irrelevant to the caller of these functions. There is a long history of using xmalloc(), xrealloc(), etc. as no-fail wrappers around the standard allocation functions, which motivates the function naming. xvalloc() and xposix_memalign() are omitted since xmemalign() suffices.

void *xmalloc(size_t size);
void *xcalloc(size_t num, size_t size);
void *xrealloc(void *ptr, size_t size);
void *xmemalign(size_t alignment, size_t size);

Memory reserve API

/*
 * The allocator maintains a memory reserve that is used to satisfy allocation
 * requests when no additional memory can be acquired from the operating
 * system.  Under normal operating conditions, the reserve size is at least
 * reserve_min bytes.  If the reserve is depleted or insufficient to satisfy an
 * allocation request, then condition notifications are sent to one or more of
 * the registered callback functions:
 *
 *   RESERVE_CND_LOW: The reserve had to be used to satisfy an allocation
 *                    request, which dropped the reserve size below the
 *                    minimum.  The callee should try to free memory in order
 *                    to restore the reserve.
 *
 *   RESERVE_CND_CRIT: The reserve was not large enough to satisfy a pending
 *                     allocation request.  Some callee must free adequate
 *                     memory in order to prevent application failure (unless
 *                     the condition spontaneously desists due to concurrent
 *                     deallocation).
 *
 *   RESERVE_CND_FAIL: An allocation request could not be satisfied, despite all
 *                     attempts.  The allocator is about to terminate the
 *                     application.
 *
 * The order in which the callback functions are called is only loosely
 * specified: in the absence of interposing callback
 * registrations/unregistrations, enabled callbacks will be called in an
 * arbitrary round-robin order.
 *
 * Condition notifications are sent to callbacks only while conditions exist.
 * For example, just before the allocator sends a RESERVE_CND_LOW condition
 * notification to a callback, the reserve is in fact depleted.  However, due
 * to allocator concurrency, the reserve may have been restored by the time the
 * callback function executes.  Furthermore, if the reserve is restored at some
 * point during the delivery of condition notifications to callbacks, no
 * further deliveries will occur, since the condition no longer exists.
 *
 * Callback functions can freely call back into the allocator (i.e. the
 * allocator releases all internal resources before calling each callback
 * function), though allocation is discouraged, since recursive callbacks are
 * likely to result, which places extra burden on the application to avoid
 * deadlock.
 *
 * Callback functions must be thread-safe, since it is possible that multiple
 * threads will call into the same callback function concurrently.
 */

/* Memory reserve condition types. */
typedef enum {
        RESERVE_CND_LOW,
        RESERVE_CND_CRIT,
        RESERVE_CND_FAIL
} reserve_cnd_t;

/*
 * Reserve condition notification callback function type definition.
 *
 * Inputs:
 *   ctx: Opaque application data, as passed to reserve_cb_register().
 *   cnd: Condition type being delivered.
 *   size: Allocation request size for the allocation that caused the condition.
 */
typedef void reserve_cb_t(void *ctx, reserve_cnd_t cnd, size_t size);

/*
 * Register a callback function.
 *
 * Inputs:
 *   cb: Callback function pointer.
 *   ctx: Opaque application data, passed to cb().
 *
 * Output:
 *   ret: If true, failure due to OOM; success otherwise.
 */
bool    reserve_cb_register(reserve_cb_t *cb, void *ctx);

/*
 * Unregister a callback function.
 *
 * Inputs:
 *   cb: Callback function pointer.
 *   ctx: Opaque application data, same as that passed to reserve_cb_register().
 *
 * Output:
 *   ret: False upon success, true if the {cb,ctx} registration could not be
 *        found.
 */
bool    reserve_cb_unregister(reserve_cb_t *cb, void *ctx);

/*
 * Get the current reserve size.
 *
 * ret: Current reserve size.
 */
size_t  reserve_cur_get(void);

/*
 * Get the minimum acceptable reserve size.  If the reserve drops below this
 * value, the RESERVE_CND_LOW condition notification is sent to the callbacks.
 *
 * ret: Minimum acceptable reserve size.
 */
size_t  reserve_min_get(void);

/*
 * Set the minimum acceptable reserve size.
 *
 * min: Reserve threshold.  This value may be internally rounded up.
 * ret: False if the reserve was successfully resized; true otherwise.  Note
 *      that failure to resize the reserve also results in a RESERVE_CND_LOW
 *      condition.
 */
bool    reserve_min_set(size_t min);

Implementation (non-)details

Internally, the allocator may manage the reserve as non-contiguous chunks of memory. This means that, for example, even with a reserve of 10MiB, the allocator may fail to allocate a 2MiB object. Similarly, even if the application makes 10MiB of non-contiguous memory available, the reserve may not increase at all, due to memory fragmentation.

If the reserve threshold is not a multiple of the allocator's internal chunk size, the actual threshold may effectively be rounded up to the nearest multiple of the chunk size. This only matters in that it limits the effective granularity with which the reserve can be configured. The chunk size for jemalloc can be queried via jemalloc_stats()[1].