MemoryBudgetManager


public final class MemoryBudgetManager
extends Object

java.lang.Object
   ↳ android.app.MemoryBudgetManager


This class is the client interface to memory budgets for applications and processes. A memory budget is a promise by the application or one of its processes that its memory requirements will not exceed some limit. The budget is not a hard limit: it can be exceeded but that will likely cause processes to slow down as they try to release memory and drop below the budget limit.

A budget declaration is not a request for memory from the system, nor does the declaration influence how the system allocates memory to a process. Budgets allow an application to monitor its own resource use.

The memory usage tracked against these budgets includes:

  • Anonymous allocations, most commonly the Java heap and native heap.
  • File-backed pages (such as files mapped into memory or cached by the process).
In the case of memory shared between processes (e.g., shared memory segments), the usage is charged to the first process that maps or allocates it.

The tracked memory usage does not include native graphics buffers or DMA-BUFs.

There are two sets of limits on memory, in addition to the budgets managed through this interface: system limits and manifest budgets (declared using <memory-budget> in AndroidManifest.xml). For each lifecycle state (foreground, perceptible, and background), a dynamic budget set through this interface is clamped to any tighter system or manifest limit in that state, so the stricter ceiling always applies. Setting a dynamic budget that exceeds a system or manifest limit in every lifecycle state for that scope throws an IllegalArgumentException without modifying active limits. Within those ceilings, a dynamic budget can be raised or lowered at any time, or removed using clearPackageBudget() or clearProcessBudget() to resume manifest or system limits.

Unlike <memory-budget> manifest clauses, which specify separate limits for foreground, perceptible, and background states, a dynamic budget sets a single runtime ceiling until updated or cleared, clamped in any state that has a tighter manifest or system limit. Applications deploying new budgets in stages can ship without <memory-budget> in AndroidManifest.xml (or with a conservative manifest ceiling), apply candidate budgets at runtime gated on remote configuration across lifecycle transitions, and call clearProcessBudget() or clearPackageBudget() for instant rollback before graduating proven steady-state budgets into AndroidManifest.xml (where PackageManager.getMemoryBudgets(ApplicationInfo) can inspect static <application> declarations).

A budget must be positive. Attempting to set a budget that is zero or negative throws an IllegalArgumentException.

A package (application) budget applies to all processes in the application as a group (specifically, all processes running under the application's UID). If the application shares a UID with other applications, the budget applies to the aggregate usage of all processes running under that shared UID.

A process budget applies to a single process. It is possible to set a large budget on a process and a small budget on the package; the package budget dominates and the large process budget is irrelevant. This is not an error.

The primary interfaces provided by this class are:

Performance and Calling Frequency

Budget mutation methods (setProcessBudgetBytes(long), clearProcessBudget(), setPackageBudgetBytes(long), and clearPackageBudget()) make interprocess calls to the system service to update the operating system's underlying memory controller for the process. Budget and usage query methods (getProcessBudgetBytes(), getPackageBudgetBytes(), getProcessCurrentUsageBytes(), and getPackageCurrentUsageBytes()) execute in-process using local native calls to inspect the memory controller directly. While lightweight, these operations are not zero-cost.

Applications should invoke budget mutations and usage queries during discrete lifecycle transitions and task milestones (such as entering or leaving an activity, starting or completing background tasks, or switching operating modes). Applications should avoid invoking these methods in tight loops, audio processing threads, or per-frame render routines.

All budget mutation methods are idempotent. Calling clearProcessBudget() or clearPackageBudget() repeatedly or when no dynamic budget is active is a safe no-op. Similarly, calling setProcessBudgetBytes(long) or setPackageBudgetBytes(long) with an already-active budget value does not trigger redundant system reconfigurations.

Over-Budget Callbacks and Threading

When memory usage exceeds an active budget, the operating system reclaims cold, unused pages first so the active working set continues to fit within the budget. While over-budget reclamation continues, registered OnOverBudgetListener callbacks are invoked repeatedly, debounced to at most once per second for each registered listener.

Because callbacks can fire while the process is under memory pressure, applications should:

Summary

Nested classes

interface MemoryBudgetManager.OnOverBudgetListener

The callback that is notified when a memory budget is exceeded.

Constants

long LIMIT_IS_DISABLED

This value is returned by getPackageBudgetBytes() and getProcessBudgetBytes() if there is no memory limit associated with the application or process, respectively.

Public methods

void clearPackageBudget()

Removes the package budget, if any, for the caller's application.

void clearProcessBudget()

Removes the process budget, if any, for the caller's process.

long getPackageBudgetBytes()

Returns the package-scope memory limit in bytes currently applied to the caller's application.

long getPackageCurrentUsageBytes()

Returns the aggregate memory usage across all processes running under the caller's application UID.

long getProcessBudgetBytes()

Returns the process-scope memory limit in bytes currently applied to the caller's process.

long getProcessCurrentUsageBytes()

Returns the current memory usage for the caller's process.

void registerPackageOverBudgetListener(Looper looper, MemoryBudgetManager.OnOverBudgetListener listener)

Registers to be notified if the caller's application exceeds its package budget.

void registerProcessOverBudgetListener(Looper looper, MemoryBudgetManager.OnOverBudgetListener listener)

Registers to be notified if the caller's process exceeds its process budget.

void setPackageBudgetBytes(long budgetBytes)

Sets a dynamic memory budget for the caller's application.

void setProcessBudgetBytes(long budgetBytes)

Sets a dynamic memory budget for the caller's process.

void unregisterPackageOverBudgetListener(MemoryBudgetManager.OnOverBudgetListener listener)

Unregisters a package budget listener.

void unregisterProcessOverBudgetListener(MemoryBudgetManager.OnOverBudgetListener listener)

Unregisters a process budget listener.

Inherited methods

Constants

LIMIT_IS_DISABLED

Added in version 37.2
public static final long LIMIT_IS_DISABLED

This value is returned by getPackageBudgetBytes() and getProcessBudgetBytes() if there is no memory limit associated with the application or process, respectively. This value may not be passed to a function that sets a budget: use the clear functions instead.

Constant Value: -1 (0xffffffffffffffff)

Public methods

clearPackageBudget

Added in version 37.2
public void clearPackageBudget ()

Removes the package budget, if any, for the caller's application. Any manifest budget or system limit that was masked by the package budget is resumed.

This operation is idempotent. Calling this method when no dynamic package budget is set is a safe no-op. This method makes an interprocess call to the system service and is intended for discrete lifecycle transitions rather than tight loops or per-frame routines.

Throws
SecurityException if the caller is not allowed to set budgets, such as from an isolated process

clearProcessBudget

Added in version 37.2
public void clearProcessBudget ()

Removes the process budget, if any, for the caller's process. Any manifest budget or system limit that was masked by the process budget is resumed.

This operation is idempotent. Calling this method when no dynamic process budget is set is a safe no-op. This method makes an interprocess call to the system service and is intended for discrete lifecycle transitions rather than tight loops or per-frame routines.

Throws
SecurityException if the caller is not allowed to set budgets, such as from an isolated process

getPackageBudgetBytes

Added in version 37.2
public long getPackageBudgetBytes ()

Returns the package-scope memory limit in bytes currently applied to the caller's application. Returns the effective limit from setPackageBudgetBytes(long) (clamped to any tighter active manifest or system limit) if a dynamic budget is set, otherwise the active <application> manifest budget or package system memory limit, or LIMIT_IS_DISABLED if unconstrained or unavailable (such as from an isolated process).

This method reads the kernel cgroup limit in-process (rounded to page size) once applied by the system service.

Returns
long the package-scope memory limit for the caller's application in bytes, or LIMIT_IS_DISABLED

getPackageCurrentUsageBytes

Added in version 37.2
public long getPackageCurrentUsageBytes ()

Returns the aggregate memory usage across all processes running under the caller's application UID.

Returns
long the current memory usage in bytes.

Throws
NumberFormatException if there is an error parsing the current usage value from the underlying memory tracking system.
SecurityException if the caller is an isolated process or access to the underlying memory tracking system is unavailable.
UnsupportedOperationException if memory budgets are not supported.

getProcessBudgetBytes

Added in version 37.2
public long getProcessBudgetBytes ()

Returns the process-scope memory limit in bytes currently applied to the caller's process. Returns the effective limit from setProcessBudgetBytes(long) (clamped to any tighter <process> manifest or system limit in the current lifecycle state) when a dynamic process budget is active, otherwise an active <process> manifest budget, or LIMIT_IS_DISABLED if no per-process limit applies in the current state (default system limits without a dynamic or <process> manifest budget apply at the package scope using getPackageBudgetBytes()).

This method reads the kernel cgroup limit in-process (rounded to page size) once applied by the system service.

Returns
long the process-scope memory limit for the caller's process in bytes, or LIMIT_IS_DISABLED

getProcessCurrentUsageBytes

Added in version 37.2
public long getProcessCurrentUsageBytes ()

Returns the current memory usage for the caller's process.

Returns
long the current memory usage in bytes.

Throws
NumberFormatException if there is an error parsing the current usage value from the underlying memory tracking system.
SecurityException if access to the underlying memory tracking system is unavailable.
UnsupportedOperationException if memory budgets are not supported.

registerPackageOverBudgetListener

Added in version 37.2
public void registerPackageOverBudgetListener (Looper looper, 
                MemoryBudgetManager.OnOverBudgetListener listener)

Registers to be notified if the caller's application exceeds its package budget. The package budget is based on the aggregate memory usage of all processes running under the same UID. An over-budget event can be triggered by memory allocations in any of these processes.

While the package remains over budget and the operating system continues reclaiming memory, the listener is invoked repeatedly, debounced to at most once per second. Callback implementations should be fast, lock-free, allocation-free, and idempotent, and avoid blocking I/O or full-process /proc memory snapshots. For one-shot notifications or a longer cooldown between cleanup passes, call unregisterPackageOverBudgetListener(OnOverBudgetListener) from inside the callback or guard cleanup work with a cooldown timestamp or AtomicBoolean.

Pass a background HandlerThread Looper rather than Looper.getMainLooper() or null (which defaults to the main Looper) unless the callback touches only lock-free, main-thread UI state. During over-budget memory reclaim, background threads may pause while holding locks (such as in logging frameworks, dependency injection containers, or databases), so acquiring locks or performing I/O on the main thread inside the callback risks priority inversion and Application Not Responding (ANR) errors.

Register this listener before calling setPackageBudgetBytes(long) so the application does not miss the initial over-budget notification when current memory usage already exceeds the newly configured budget.

An OnOverBudgetListener callback can only be registered once.

Parameters
looper Looper: the Looper whose thread dispatches OnOverBudgetListener callbacks, or null to use Looper.getMainLooper()
listener MemoryBudgetManager.OnOverBudgetListener: callback to be notified of an over-budget event.
This value cannot be null.

Throws
IllegalArgumentException if a looper is not provided and one can't be found on the current thread.
IllegalStateException if registration fails
SecurityException if the caller is an isolated process.

registerProcessOverBudgetListener

Added in version 37.2
public void registerProcessOverBudgetListener (Looper looper, 
                MemoryBudgetManager.OnOverBudgetListener listener)

Registers to be notified if the caller's process exceeds its process budget. This listener will only be notified of breaches due to memory allocations within the calling process.

While the process remains over budget and the operating system continues reclaiming memory, the listener is invoked repeatedly, debounced to at most once per second. Callback implementations should be fast, lock-free, allocation-free, and idempotent, and avoid blocking I/O or full-process /proc memory snapshots. For one-shot notifications or a longer cooldown between cleanup passes, call unregisterProcessOverBudgetListener(OnOverBudgetListener) from inside the callback or guard cleanup work with a cooldown timestamp or AtomicBoolean.

Pass a background HandlerThread Looper rather than Looper.getMainLooper() or null (which defaults to the main Looper) unless the callback touches only lock-free, main-thread UI state. During over-budget memory reclaim, background threads may pause while holding locks (such as in logging frameworks, dependency injection containers, or databases), so acquiring locks or performing I/O on the main thread inside the callback risks priority inversion and Application Not Responding (ANR) errors.

Register this listener before calling setProcessBudgetBytes(long) so the application does not miss the initial over-budget notification when current memory usage already exceeds the newly configured budget.

An OnOverBudgetListener callback can only be registered once.

Parameters
looper Looper: the Looper whose thread dispatches OnOverBudgetListener callbacks, or null to use Looper.getMainLooper()
listener MemoryBudgetManager.OnOverBudgetListener: callback to be notified of an over-budget event.
This value cannot be null.

Throws
IllegalArgumentException if a looper is not provided and one can't be found on the current thread.
IllegalStateException if registration fails

setPackageBudgetBytes

Added in version 37.2
public void setPackageBudgetBytes (long budgetBytes)

Sets a dynamic memory budget for the caller's application. The budget caps cumulative memory use across all processes within the application until updated or cleared with clearPackageBudget(), clamped in each lifecycle state to any tighter system or <application> <memory-budget> state limit. This does not affect any per-process budgets within the application.

budgetBytes must be positive (> 0). Setting a budget that exceeds a system or <application> <memory-budget> limit in every lifecycle state throws an IllegalArgumentException without modifying active limits.

If current package memory usage already exceeds the resulting active limit, an over-budget event is triggered as soon as the new budget is applied. Because listeners only receive events that occur after registration completes, register any OnOverBudgetListener using registerPackageOverBudgetListener(Looper, OnOverBudgetListener) before calling this method so the initial over-budget notification is not missed.

This operation is idempotent. Setting the same budget value consecutively does not trigger redundant system reconfigurations. This method makes an interprocess call to the system service and is intended for discrete lifecycle transitions rather than tight loops or per-frame routines.

Parameters
budgetBytes long: the declared budget, in bytes (must be > 0)
Value is 0 or greater
Throws
IllegalArgumentException if budgetBytes <= 0 or exceeds a system or <memory-budget> limit for the package in every lifecycle state
SecurityException if the caller is not allowed to set budgets, such as from an isolated process

setProcessBudgetBytes

Added in version 37.2
public void setProcessBudgetBytes (long budgetBytes)

Sets a dynamic memory budget for the caller's process. The budget caps process memory use across process lifecycle transitions until updated or cleared with clearProcessBudget(), clamped in each lifecycle state to any tighter system or <process> <memory-budget> state limit.

budgetBytes must be positive (> 0). Setting a budget that exceeds a system or <process> <memory-budget> limit in every lifecycle state throws an IllegalArgumentException without modifying active limits.

If current process memory usage already exceeds the resulting active limit, an over-budget event is triggered as soon as the new budget is applied. Because listeners only receive events that occur after registration completes, register any OnOverBudgetListener using registerProcessOverBudgetListener(Looper, OnOverBudgetListener) before calling this method so the initial over-budget notification is not missed.

This operation is idempotent. Setting the same budget value consecutively does not trigger redundant system reconfigurations. This method makes an interprocess call to the system service and is intended for discrete lifecycle transitions rather than tight loops or per-frame routines.

Parameters
budgetBytes long: the declared budget, in bytes (must be > 0)
Value is 0 or greater
Throws
IllegalArgumentException if budgetBytes <= 0 or exceeds a system or <memory-budget> limit for the process in every lifecycle state
SecurityException if the caller is not allowed to set budgets, such as from an isolated process

unregisterPackageOverBudgetListener

Added in version 37.2
public void unregisterPackageOverBudgetListener (MemoryBudgetManager.OnOverBudgetListener listener)

Unregisters a package budget listener.

Parameters
listener MemoryBudgetManager.OnOverBudgetListener: The callback to be notified of an over-budget event.
This value cannot be null.

Throws
IllegalStateException if the listener was not registered.

unregisterProcessOverBudgetListener

Added in version 37.2
public void unregisterProcessOverBudgetListener (MemoryBudgetManager.OnOverBudgetListener listener)

Unregisters a process budget listener.

Parameters
listener MemoryBudgetManager.OnOverBudgetListener: The callback to be notified of an over-budget event.
This value cannot be null.

Throws
IllegalStateException if the listener was not registered.