Out-of-Memory Handling

Typedefs
typedef void(*	xaOOMCallback) (int phase, size_t allocsz)

Enumerations
enum	XA_OOM_PHASE_ENUM { XA_LowEffort = 1 , XA_HighEffort , XA_Urgent , XA_Fatal = -1 }
	Phases of out-of-memory handling, indicating escalating urgency. More...

Functions
void	xaAddOOMCallback (xaOOMCallback cb)
void	xaRemoveOOMCallback (xaOOMCallback cb)

Detailed Description

System for registering callbacks to handle memory pressure situations.

Typedef Documentation

xaOOMCallback

typedef void(* xaOOMCallback) (int phase, size_t allocsz)

In an out-of-memory situation, all registered OOM callbacks will be called. Depending on the type of allocation, they may be called repeatedly with different phases – see the phase enum above for details on how to handle each phase. It is guaranteed that only one thread will be inside an OOM callback at a time – all other threads must wait on the first thread to enter the callback to return.

Parameters

phase	One of the XA_OOM_PHASE_ENUM values indicating urgency level
allocsz	The size of the allocation that triggered the OOM condition

Definition at line 168 of file xalloc.h.

Enumeration Type Documentation

XA_OOM_PHASE_ENUM

enum XA_OOM_PHASE_ENUM

Phases of out-of-memory handling, indicating escalating urgency.

Enumerator
XA_LowEffort	In the low-effort phase, the OOM handler should try to free memory that is low-hanging fruit. It MUST NOT acquire any locks, even optimistically. This phase is best suited for freeing memory that is known garbage and is for certain not in use, such as a deferred-free scenario.
XA_HighEffort	In the high-effort phase, the OOM handler may optimistically acquire locks in a non-blocking manner, but MUST NOT wait on a lock. This phase is suited for cleaning up cache memory or other nonessential resources.
XA_Urgent	In the urgent phase, the OOM handler should go to any lengths necessary to free memory, including waiting on locks, but be careful to avoid possible deadlocks. The urgent phase is only invoked as a last-ditch effort before asserting and crashing the program.
XA_Fatal	The fatal phase occurs only if a non-optional allocation has exhausted all options and is about to trigger an assertion. It can be used for a program to intervene and exit in some other manner, but be aware that it is quite likely there is little or no memory available and any allocations will fail.

Definition at line 121 of file xalloc.h.

Function Documentation

xaAddOOMCallback()

void xaAddOOMCallback

(

xaOOMCallback

cb

)

Install function to call in out-of-memory conditions

Parameters

cb	Callback function to register

xaRemoveOOMCallback()

void xaRemoveOOMCallback

(

xaOOMCallback

cb

)

Remove a previously installed OOM callback

Parameters

cb	Callback function to unregister