chromium/content/public/browser/page_user_data.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_USER_DATA_H_
#define CONTENT_PUBLIC_BROWSER_PAGE_USER_DATA_H_

#include "base/memory/ptr_util.h"
#include "base/memory/raw_ref.h"
#include "base/supports_user_data.h"
#include "content/public/browser/page.h"

namespace content {

// A base class for classes attached to, and scoped to, the lifetime of a
// content::Page.

// PageUserData is created when a user of an API inherits this class and calls
// CreateForPage.
//
// PageUserData is similar to DocumentUserData, but is attached to the
// page (1:1 with main document) instead of any document. Prefer using
// PageUserData for main-document-only data.
//
// Example usage of PageUserData:
//
// --- in foo_page_helper.h ---
// class FooPageHelper : public content::PageUserData<FooPageHelper> {
//  public:
//   ~FooPageHelper() override;
//
//   // ... more public stuff here ...
//
//  private:
//   explicit FooPageHelper(content::Page& page);
//
//   friend PageUserData;
//   PAGE_USER_DATA_KEY_DECL();
//
//   // ... more private stuff here ...
// };
//
// --- in foo_page_helper.cc ---
// PAGE_USER_DATA_KEY_IMPL(FooPageHelper);
//
// FooPageHelper::FooPageHelper(content::Page& page)
//     : PageUserData(page) {}
//
// FooPageHelper::~FooPageHelper() {}
//
template <typename T>
class PageUserData : public base::SupportsUserData::Data { … };

// Users won't be able to instantiate the template if they miss declaring the
// user data key.
// This macro declares a static variable inside the class that inherits from
// PageUserData. The address of this static variable is used as
// the key to store/retrieve an instance of the class.
#define PAGE_USER_DATA_KEY_DECL() …

// This macro instantiates the static variable declared by the previous macro.
// It must live in a .cc file to ensure that there is only one instantiation
// of the static variable.
#define PAGE_USER_DATA_KEY_IMPL(Type) …

}  // namespace content

#endif  // CONTENT_PUBLIC_BROWSER_PAGE_USER_DATA_H_