identifiable_surface.h | Explore in Territory

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

#ifndef THIRD_PARTY_BLINK_PUBLIC_COMMON_PRIVACY_BUDGET_IDENTIFIABLE_SURFACE_H_
#define THIRD_PARTY_BLINK_PUBLIC_COMMON_PRIVACY_BUDGET_IDENTIFIABLE_SURFACE_H_

#include <stdint.h>

#include <algorithm>
#include <compare>
#include <cstddef>
#include <functional>
#include <tuple>

#include "services/metrics/public/cpp/ukm_builders.h"
#include "third_party/blink/public/common/privacy_budget/identifiable_token.h"

namespace blink {

// An identifiable surface.
//
// See also: ../../../../../docs/privacy_budget/good_identifiable_surface.md
//
// This class intends to be a lightweight wrapper over a simple 64-bit integer.
// It exhibits the following characteristics:
//
//   * All methods are constexpr.
//   * Immutable.
//   * Efficient enough to pass by value.
//
// Internally, an identifiable surface is represented as a 64-bit unsigned
// integer that can be used as the metric hash for reporting metrics via UKM.
//
// The least-significant |kTypeBits| of the value is used to store
// a IdentifiableSurface::Type value. The remainder stores the 56
// least-significant bits of an `IdentifiableToken` as illustrated below:
//              ✂
//    ┌─────────┊────────────────────────────────────────┐ ┌──────────┐
//    │(discard)✂           IdentifiableToken            │ │   Type   │
//    └─────────┊───────────────────┬────────────────────┘ └────┬─────┘
// Bit 64       ┊55                 ┊                   0   7   ┊    0
//              ✂                   ↓                           ↓
//              ┌────────────────────────────────────────┬──────────┐
//              │                                        │          │
//              └────────────────────────────────────────┴──────────┘
//           Bit 64                                     8 7        0
//              │←────────────── IdentifiableSurface ──────────────→│
//
// Only the lower 56 bits of `IdentifiableToken` contribute to an
// `IdentifiableSurface`.
//
// See descriptions for the `Type` enum values for details on how the
// `IdentifiableToken` is generated for each type. The descriptions use the
// following notation to indicate how the value is recorded:
//
//     IdentifiableSurface = { IdentifiableToken value, Type value }
//     Value = [description of how the value is constructed]
class IdentifiableSurface { … };

// Hash function compatible with std::hash.
struct IdentifiableSurfaceHash { … };

}  // namespace blink

#endif  // THIRD_PARTY_BLINK_PUBLIC_COMMON_PRIVACY_BUDGET_IDENTIFIABLE_SURFACE_H_
chromium/third_party/blink/public/common/privacy_budget/identifiable_surface.h
