Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions) Summary: [Nested Classes](https://developer.android.com/reference/android/app/MemoryBudgetManager#nestedclasses) \| [Constants](https://developer.android.com/reference/android/app/MemoryBudgetManager#constants) \| [Methods](https://developer.android.com/reference/android/app/MemoryBudgetManager#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/app/MemoryBudgetManager#inhmethods)

# MemoryBudgetManager

*** ** * ** ***


`
public

final

class
MemoryBudgetManager
`


`

extends https://developer.android.com/reference/java/lang/Object


`

`


`

|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.app.MemoryBudgetManager |

<br />

*** ** * ** ***

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. There are system limits and manifest budgets (declared via `<memory-budget>`
in the manifest). 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
`https://developer.android.com/reference/java/lang/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 `https://developer.android.com/reference/java/lang/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:

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

<br />

## Summary

| ### Nested classes ||
|---|---|
| ` interface` | `https://developer.android.com/reference/android/app/MemoryBudgetManager.OnOverBudgetListener` The callback that is notified when a budget is exceeded. |

| ### Constants ||
|---|---|
| `long` | `https://developer.android.com/reference/android/app/MemoryBudgetManager#LIMIT_IS_DISABLED` This value is returned by `https://developer.android.com/reference/android/app/MemoryBudgetManager#getPackageBudgetBytes()` and `https://developer.android.com/reference/android/app/MemoryBudgetManager#getProcessBudgetBytes()` if there is no memory limit associated with the application or process, respectively. |

| ### Public methods ||
|---|---|
| ` void` | ` https://developer.android.com/reference/android/app/MemoryBudgetManager#clearPackageBudget()() ` Removes the package budget, if any, for the caller's application. |
| ` void` | ` https://developer.android.com/reference/android/app/MemoryBudgetManager#clearProcessBudget()() ` Removes the process budget, if any, for the caller's process. |
| ` long` | ` https://developer.android.com/reference/android/app/MemoryBudgetManager#getPackageBudgetBytes()() ` Returns the budget for the caller's application. |
| ` long` | ` https://developer.android.com/reference/android/app/MemoryBudgetManager#getPackageCurrentUsageBytes()() ` Returns the aggregate memory usage across all processes running under the caller's application UID. |
| ` long` | ` https://developer.android.com/reference/android/app/MemoryBudgetManager#getProcessBudgetBytes()() ` Returns the budget for the caller's process. |
| ` long` | ` https://developer.android.com/reference/android/app/MemoryBudgetManager#getProcessCurrentUsageBytes()() ` Returns the current memory usage for the caller's process. |
| ` void` | ` https://developer.android.com/reference/android/app/MemoryBudgetManager#registerPackageOverBudgetListener(android.os.Looper,%20android.app.MemoryBudgetManager.OnOverBudgetListener)(https://developer.android.com/reference/android/os/Looper looper, https://developer.android.com/reference/android/app/MemoryBudgetManager.OnOverBudgetListener listener) ` Registers to be notified if the caller's application exceeds its package budget. |
| ` void` | ` https://developer.android.com/reference/android/app/MemoryBudgetManager#registerProcessOverBudgetListener(android.os.Looper,%20android.app.MemoryBudgetManager.OnOverBudgetListener)(https://developer.android.com/reference/android/os/Looper looper, https://developer.android.com/reference/android/app/MemoryBudgetManager.OnOverBudgetListener listener) ` Registers to be notified if the caller's process exceeds its process budget. |
| ` void` | ` https://developer.android.com/reference/android/app/MemoryBudgetManager#setPackageBudgetBytes(long)(long budgetBytes) ` Sets the memory budget for the caller's application. |
| ` void` | ` https://developer.android.com/reference/android/app/MemoryBudgetManager#setProcessBudgetBytes(long)(long budgetBytes) ` Sets the memory budget for the caller's process. |
| ` void` | ` https://developer.android.com/reference/android/app/MemoryBudgetManager#unregisterPackageOverBudgetListener(android.app.MemoryBudgetManager.OnOverBudgetListener)(https://developer.android.com/reference/android/app/MemoryBudgetManager.OnOverBudgetListener listener) ` Unregisters a package budget listener. |
| ` void` | ` https://developer.android.com/reference/android/app/MemoryBudgetManager#unregisterProcessOverBudgetListener(android.app.MemoryBudgetManager.OnOverBudgetListener)(https://developer.android.com/reference/android/app/MemoryBudgetManager.OnOverBudgetListener listener) ` Unregisters a process budget listener. |

### Inherited methods

From class `

https://developer.android.com/reference/java/lang/Object

` `


https://developer.android.com/reference/java/lang/Object` `
https://developer.android.com/reference/java/lang/Object#clone()()
`

Creates and returns a copy of this object.


`


boolean` `
https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj)
`

Indicates whether some other object is "equal to" this one.


`


void` `
https://developer.android.com/reference/java/lang/Object#finalize()()
`

Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.


`


final

https://developer.android.com/reference/java/lang/Class<?>` `
https://developer.android.com/reference/java/lang/Object#getClass()()
`

Returns the runtime class of this `Object`.


`


int` `
https://developer.android.com/reference/java/lang/Object#hashCode()()
`

Returns a hash code value for the object.


`


final

void` `
https://developer.android.com/reference/java/lang/Object#notify()()
`

Wakes up a single thread that is waiting on this object's
monitor.


`


final

void` `
https://developer.android.com/reference/java/lang/Object#notifyAll()()
`

Wakes up all threads that are waiting on this object's monitor.


`


https://developer.android.com/reference/java/lang/String` `
https://developer.android.com/reference/java/lang/Object#toString()()
`

Returns a string representation of the object.


`


final

void` `
https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(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` `
https://developer.android.com/reference/java/lang/Object#wait(long)(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` `
https://developer.android.com/reference/java/lang/Object#wait()()
`

Causes the current thread to wait until it is awakened, typically
by being *notified* or *interrupted*.


## Constants

### LIMIT_IS_DISABLED

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
public static final long LIMIT_IS_DISABLED
```

This value is returned by `https://developer.android.com/reference/android/app/MemoryBudgetManager#getPackageBudgetBytes()` and
`https://developer.android.com/reference/android/app/MemoryBudgetManager#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.

<br />

Constant Value:

-1
(0xffffffffffffffff)


## Public methods

### clearPackageBudget

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
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.

<br />

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/SecurityException` | if the caller is not allowed to set budgets, such as from an isolated process |

### clearProcessBudget

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
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.

<br />

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/SecurityException` | if the caller is not allowed to set budgets, such as from an isolated process |

### getPackageBudgetBytes

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
public long getPackageBudgetBytes ()
```

Returns the budget for the caller's application. The value returned will be the last value
set via `https://developer.android.com/reference/android/app/MemoryBudgetManager#setPackageBudgetBytes(long)`, if any, or the existing system or manifest
limit, if there is no package budget.

<br />

| Returns ||
|---|---|
| `long` | memory limit for the caller's application in bytes; may return `LIMIT_IS_DISABLED` <br /> |

### getPackageCurrentUsageBytes

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
public long getPackageCurrentUsageBytes ()
```

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

<br />

| Returns ||
|---|---|
| `long` | the current memory usage in bytes. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NumberFormatException` | if there is an error parsing the current usage value from the underlying memory tracking system. |
| `https://developer.android.com/reference/java/lang/SecurityException` | if the caller is an isolated process or access to the underlying memory tracking system is unavailable. |
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException` | if memory budgets are not supported. |

### getProcessBudgetBytes

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
public long getProcessBudgetBytes ()
```

Returns the budget for the caller's process. The value returned will be the last value set
via `https://developer.android.com/reference/android/app/MemoryBudgetManager#setProcessBudgetBytes(long)`, if any, or the existing system or manifest limit,
if there is no process budget.

<br />

| Returns ||
|---|---|
| `long` | memory limit for the caller's process in bytes; may return `LIMIT_IS_DISABLED` <br /> |

### getProcessCurrentUsageBytes

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
public long getProcessCurrentUsageBytes ()
```

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

<br />

| Returns ||
|---|---|
| `long` | the current memory usage in bytes. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NumberFormatException` | if there is an error parsing the current usage value from the underlying memory tracking system. |
| `https://developer.android.com/reference/java/lang/SecurityException` | if access to the underlying memory tracking system is unavailable. |
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException` | if memory budgets are not supported. |

### registerPackageOverBudgetListener

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
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.


An OnOverBudgetListener callback can only be registered once.

<br />

| Parameters ||
|---|---|
| `looper` | `Looper`: `https://developer.android.com/reference/android/app/MemoryBudgetManager.OnOverBudgetListener` callbacks will be dispatched on this Looper's thread. If `null`, the looper from Looper.getMainLooper() will be used. <br /> |
| `listener` | `MemoryBudgetManager.OnOverBudgetListener`: callback to be notified of an over-budget event. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if a looper is not provided and one can't be found on the current thread. |
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if registration fails |
| `https://developer.android.com/reference/java/lang/SecurityException` | if the caller is an isolated process. |

### registerProcessOverBudgetListener

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
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.


An OnOverBudgetListener callback can only be registered once.

<br />

| Parameters ||
|---|---|
| `looper` | `Looper`: `https://developer.android.com/reference/android/app/MemoryBudgetManager.OnOverBudgetListener` callbacks will be dispatched on this Looper's thread. If `null`, the looper from Looper.getMainLooper() will be used. <br /> |
| `listener` | `MemoryBudgetManager.OnOverBudgetListener`: callback to be notified of an over-budget event. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if a looper is not provided and one can't be found on the current thread. |
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if registration fails |

### setPackageBudgetBytes

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
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.

<br />

| Parameters ||
|---|---|
| `budgetBytes` | `long`: declared budget, in bytes. Value is 0 or greater <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the budget is invalid. |
| `https://developer.android.com/reference/java/lang/SecurityException` | if the caller is not allowed to set budgets, such as from an isolated process |

### setProcessBudgetBytes

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
public void setProcessBudgetBytes (long budgetBytes)
```

Sets the memory budget for the caller's process.

<br />

| Parameters ||
|---|---|
| `budgetBytes` | `long`: declared budget, in bytes. Value is 0 or greater <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the budget is invalid. |
| `https://developer.android.com/reference/java/lang/SecurityException` | if the caller is not allowed to set budgets, such as from an isolated process |

### unregisterPackageOverBudgetListener

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
public void unregisterPackageOverBudgetListener (MemoryBudgetManager.OnOverBudgetListener listener)
```

Unregisters a package budget listener.

<br />

| Parameters ||
|---|---|
| `listener` | `MemoryBudgetManager.OnOverBudgetListener`: The callback to be notified of an over-budget event. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if the listener was not registered. |

### unregisterProcessOverBudgetListener

Added in [version 37.2](https://developer.android.com/topic/libraries/support-library/revisions)

```
public void unregisterProcessOverBudgetListener (MemoryBudgetManager.OnOverBudgetListener listener)
```

Unregisters a process budget listener.

<br />

| Parameters ||
|---|---|
| `listener` | `MemoryBudgetManager.OnOverBudgetListener`: The callback to be notified of an over-budget event. This value cannot be `null`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException` | if the listener was not registered. |