f8/sdk/fidl/fuchsia.memorypressure/README.md

<link rel="stylesheet" href="../style.css" />

[TOC]
# fuchsia.memorypressure

<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 7</span></div>

## **PROTOCOLS**

## Provider {#Provider}
*Defined in [fuchsia.memorypressure/memorypressure.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.memorypressure/memorypressure.fidl;l=47)*
<p>Registration protocol</p>

### RegisterWatcher {#Provider.RegisterWatcher}

<p>Used to register for memory pressure level changes.
<code>watcher</code>: memory pressure <code>Watcher</code> channel that the <code>Provider</code> will use to send
level change messages to the client.</p>
<p>The current memory pressure level is immediately sent to the watcher
when this method is called.</p>
<p>It is recommended that the root job in a component tree register for changes,
rather than having individual jobs further down the tree register individually.
A low client count will help minimize system churn due to a large number of
memory pressure messages in transit at the same time.
Also, the more context a job has, the better equipped it will be to react to
memory pressure by controlling the behavior of children jobs in its tree.</p>

#### Request {#Provider.RegisterWatcher_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>watcher</code></td>
            <td>
                <code><a class='link' href='#Watcher'>Watcher</a></code>
            </td>
        </tr>
</table>


## Watcher {#Watcher}
*Defined in [fuchsia.memorypressure/memorypressure.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.memorypressure/memorypressure.fidl;l=68)*
<p>Watcher protocol
To be implemented by clients who wish to be notified on memory pressure level changes.</p>

### OnLevelChanged {#Watcher.OnLevelChanged}

<p>Sent to the registered client when the memory pressure level changes.
<code>level</code>: indicates the current memory pressure level.</p>
<p>Will also be invoked on initial connection via <code>RegisterWatcher</code>, so that a newly
registered client can discover the current memory pressure level.</p>
<p>The watcher must immediately reply with a message to acknowledge that it has
received the level change notification, and has initiated required actions as a
result. It may then continue to reclaim memory asynchronously after sending
the acknowledgement.</p>
<p>Some helpful guidelines for clients:</p>
<ol>
<li>
<p>The watcher will be notified of new pressure level changes only after a reply
corresponding to the previous message has been received by the provider.
If multiple level transitions occur during that time, the watcher will be
notified of the latest pressure level.</p>
</li>
<li>
<p>The level changes are edge-triggered, and clients are expected to maintain
local state to track the current pressure level, if required. For example,
a job might be notified of a CRITICAL level and drop all its caches as a result.
Some time after this, it might want to trigger an activity that causes a
fair amount of memory to be allocated. At this point, the job is expected to
remember that the last pressure level it saw was CRITICAL, and refrain from
triggering the memory-intensive activity.</p>
</li>
<li>
<p>As a performance optimization, the provider may decide to skip sending
messages for some pressure level changes. For example, when oscillating across
the NORMAL / WARNING boundary, it might not be worth notifying clients of every
single transition. The provider might rate-limit messages in this case.
On a similar note, the provider may decide to send repeated messages at the
same pressure level, particularly CRITICAL, to indicate that further action
needs to be taken.</p>
</li>
</ol>

#### Request {#Watcher.OnLevelChanged_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>level</code></td>
            <td>
                <code><a class='link' href='#Level'>Level</a></code>
            </td>
        </tr>
</table>


#### Response {#Watcher.OnLevelChanged_Response}

&lt;EMPTY&gt;



## **ENUMS**

### Level [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#Level data-text="Level"}
Type: <code>uint32</code>

*Defined in [fuchsia.memorypressure/memorypressure.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.memorypressure/memorypressure.fidl;l=8)*
<p>Indicates the memory pressure level.</p>

<table>
    <tr><th>Name</th><th>Value</th><th>Description</th></tr>
        <tr id="Level.NORMAL">
<td><h3 id="Level.NORMAL" class="add-link hide-from-toc">NORMAL</h3></td>
            <td><code>1</code></td>
            <td><p>The memory pressure level is healthy.</p>
<p>Registered clients are free to hold on to caches and allocate memory
unrestricted.</p>
<p>However, clients should take care to not proactively re-create caches on a
transition back to the NORMAL level, causing a memory spike that immediately
pushes the level over to WARNING again.</p>
</td>
        </tr>
        <tr id="Level.WARNING">
<td><h3 id="Level.WARNING" class="add-link hide-from-toc">WARNING</h3></td>
            <td><code>2</code></td>
            <td><p>The memory pressure level is somewhat constrained, and might cross over to
the critical pressure range if left unchecked.</p>
<p>Registered clients are expected to optimize their operation to limit memory
usage, rather than for best performance, for example, by reducing cache sizes
and non-essential memory allocations.</p>
<p>Clients must take care to regulate the amount of work they undertake in
order to reclaim memory, and ensure that it does not cause visible
performance degradation. There exists some memory pressure, but not enough
to justify trading off user responsiveness to reclaim memory.</p>
</td>
        </tr>
        <tr id="Level.CRITICAL">
<td><h3 id="Level.CRITICAL" class="add-link hide-from-toc">CRITICAL</h3></td>
            <td><code>3</code></td>
            <td><p>The memory pressure level is very constrained.</p>
<p>Registered clients are expected to drop all non-essential memory, and refrain
from allocating more memory. Failing to do so might result in the job
getting terminated, or the system being rebooted in the case of global
memory pressure.</p>
<p>Clients may undertake expensive work to reclaim memory if required, since
failing to do so might result in termination. The client might decide that a
performance hit is a fair tradeoff in this case.</p>
</td>
        </tr>
</table>