Added in API level 10000

Summary: Nested Classes | Constants | Methods | Inherited Methods

MemoryBudgetManager

---

Kotlin |Java

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.

There are two sets of limits on memory, in addition to the budgets managed through this interface. There are system limits and manifest budgets. Budgets managed through this interface may not exceed the system or manifest limits. Any attempt to exceed the system or manifest limits will result in an IllegalArgumentException. However, the budget set through this interface can be changed at any time, up or down, so long as the new value does not exceed the system or manifest limits.

A budget must be positive; attempting to set a budget that is zero or negative will result in an IllegalArgumentException.

A package (application) budget applies to all processes in the application, as a group. 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:

• Memory Budget Configuration:
  • setPackageBudgetBytes(long) / clearPackageBudget() - Sets or clears the memory budget for the application.
  • setProcessBudgetBytes(long) / clearProcessBudget() - Sets or clears the memory budget for the calling process.
• Memory Budget Queries:
  • getPackageBudgetBytes() - Returns the current budget for the application.
  • getProcessBudgetBytes() - Returns the current budget for the calling process.
• Memory Usage Queries:
  • getPackageCurrentUsageBytes() - Returns the aggregate memory usage across all processes in the application package.
  • getProcessCurrentUsageBytes() - Returns the memory usage for the caller's specific process.
• Over-Budget Event Monitoring:
  • OnOverBudgetListener - Callback interface notified when memory usage exceeds a budget threshold.
  • registerPackageOverBudgetListener(Looper,OnOverBudgetListener) / unregisterPackageOverBudgetListener(OnOverBudgetListener) - Registers or unregisters listeners for package-level budget breaches.
  • registerProcessOverBudgetListener(Looper,OnOverBudgetListener) / unregisterProcessOverBudgetListener(OnOverBudgetListener) - Registers or unregisters listeners for process-level budget breaches.

Summary

Nested classes
interface	MemoryBudgetManager.OnOverBudgetListener The callback that is notified when a 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 budget for the caller's application.
long	getPackageCurrentUsageBytes() Returns the current memory usage for the caller's application.
long	getProcessBudgetBytes() Returns the budget for 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 the memory budget for the caller's application.
void	setProcessBudgetBytes(long budgetBytes) Sets the 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

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

LIMIT_IS_DISABLED

Added in API level 10000

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 API level 10000

public void clearPackageBudget ()

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

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

clearProcessBudget

Added in API level 10000

public void clearProcessBudget ()

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

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

getPackageBudgetBytes

Added in API level 10000

public long getPackageBudgetBytes ()

Returns the budget for the caller's application. The value returned will be the last value set via setPackageBudgetBytes(long), if any, or the existing system or manifest limit, if there is no package budget.

Returns
long	memory limit for the caller's application in bytes; may return LIMIT_IS_DISABLED

getPackageCurrentUsageBytes

Added in API level 10000

public long getPackageCurrentUsageBytes ()

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

Returns
long	the current memory usage in bytes.

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

getProcessBudgetBytes

Added in API level 10000

public long getProcessBudgetBytes ()

Returns the budget for the caller's process. The value returned will be the last value set via setProcessBudgetBytes(long), if any, or the existing system or manifest limit, if there is no process budget.

Returns
long	memory limit for the caller's process in bytes; may return LIMIT_IS_DISABLED

getProcessCurrentUsageBytes

Added in API level 10000

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 cgroup file.
SecurityException	if access to the underlying memory cgroup is unavailable.
UnsupportedOperationException	if memory budgets are not supported.

registerPackageOverBudgetListener

Added in API level 10000

public void registerPackageOverBudgetListener (Looper looper, 
                MemoryBudgetManager.OnOverBudgetListener listener)

Registers to be notified if the caller's application exceeds its package budget. An OnOverBudgetListener callback can only be registered once.

Parameters
looper	Looper: OnOverBudgetListener callbacks will be dispatched on this Looper's thread. If null, the looper from Looper.getMainLooper() will be used.
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 API level 10000

public void registerProcessOverBudgetListener (Looper looper, 
                MemoryBudgetManager.OnOverBudgetListener listener)

Registers to be notified if the caller's process exceeds its process budget. An OnOverBudgetListener callback can only be registered once.

Parameters
looper	Looper: OnOverBudgetListener callbacks will be dispatched on this Looper's thread. If null, the looper from Looper.getMainLooper() will be used.
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 API level 10000

public void setPackageBudgetBytes (long budgetBytes)

Sets the memory budget for the caller's application. The budget applies to the cumulative memory use by all processes within the application. This does not affect any budgets for processes within the application.

Parameters
budgetBytes	long: declared budget, in bytes. Value is 0 or greater

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

setProcessBudgetBytes

Added in API level 10000

public void setProcessBudgetBytes (long budgetBytes)

Sets the memory budget for the caller's process.

Parameters
budgetBytes	long: declared budget, in bytes. Value is 0 or greater

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

unregisterPackageOverBudgetListener

Added in API level 10000

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 API level 10000

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.