chromium/content/public/browser/page.h

// Copyright 2021 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef CONTENT_PUBLIC_BROWSER_PAGE_H_
#define CONTENT_PUBLIC_BROWSER_PAGE_H_

#include <optional>

#include "base/functional/callback.h"
#include "base/supports_user_data.h"
#include "content/common/content_export.h"
#include "content/public/browser/render_frame_host.h"
#include "third_party/blink/public/mojom/manifest/manifest.mojom-forward.h"
#include "third_party/perfetto/include/perfetto/tracing/traced_value_forward.h"
#include "url/gurl.h"

namespace content {

// Page represents a collection of documents with the same main document.

// At the moment some navigations might create a new blink::Document in the
// existing RenderFrameHost, which will lead to a creation of a new Page
// associated with the same main RenderFrameHost. See the comment in
// |DocumentUserData| for more details and crbug.com/936696 for the
// progress on always creating a new RenderFrameHost for each new document.

// Page is created when a main document is created, which can happen in the
// following ways:
// 1) Main RenderFrameHost is created.
// 2) A cross-document non-bfcached navigation is committed in the same
//    RenderFrameHost.
// 3) Main RenderFrameHost is re-created after crash.

// Page is deleted in the following cases:
// 1) Main RenderFrameHost is deleted. Note that this might be different from
//    when the navigation commits, see the comment in
//    RenderFrameHost::LifecycleState::kPendingDeletion for more details.
// 2) A cross-document non-bfcached navigation is committed in the same
//    RenderFrameHost.
// 3) Before main RenderFrameHost is re-created after crash.

// If a method can be called only for main RenderFrameHosts or if its behaviour
// is identical when called on the parent / child RenderFrameHosts, it should
// be added to Page(Impl).

// With Multiple Page Architecture (MPArch), each WebContents may have
// additional FrameTrees which will have their own associated Page. Please take
// into consideration when assuming that Page is appropriate for storing
// something that's common for all frames you see on a tab.
// See docs/frame_trees.md for more details.

// NOTE: Depending on the process model, the cross-origin iframes are likely to
// be hosted in a different renderer process than the main document, so a given
// page is hosted in multiple renderer processes at the same time.
// RenderViewHost / `blink::WebView` / blink::Page (which are all 1:1:1)
// represent a part of a given content::Page in a given renderer process (note,
// however, that like RenderFrameHosts, these objects at the moment can be
// reused for a new content::Page for a cross-document same-site main-frame
// navigation).
class CONTENT_EXPORT Page : public base::SupportsUserData { … };

}  // namespace content

#endif  // CONTENT_PUBLIC_BROWSER_PAGE_H_