android_webview/docs/lifetime-annotations.md

# Lifetime annotations

[TOC]

## Overview

As part of the WebView Multi-profile project, classes and state in
`//android_webview/`` will be annotated to make their lifetimes explicit.
There are broadly 4 different lifetimes that a class can have:

- Singleton - there is one instance of this class per WebView process. As
  WebView is run in the embedding app's process, this means there is one
  instance per embedding app.
- Scoped to Profile - this class is specific to a Profile. It is likely to do
  with the user's browsing state, such as cookies or permissions.
- Scoped to WebView - this class is specific to a WebView (the Android View),
  for example the AwZoomControls.
- Temporary - this class has a shorter lifetime than a WebView, likely just
  existing within a call stack, for example return types.

There is a many to one relationship between WebViews and Profiles. A single
Profile can support multiple WebViews, each WebView will only have a single
(constant) Profile.

These annotations are purely for documentation, there is no static analysis to
check them.

## Annotations

In Java, use the following annotations:

- `@Lifetime.Singleton`
- `@Lifetime.Profile`
- `@Lifetime.WebView`
- `@Lifetime.Temporary`

In C++, use the following comment format as the last line of the classes
documentation:

```
 * Lifetime: Singleton
 * Lifetime: Profile
 * Lifetime: WebView
 * Lifetime: Temporary
```