ceph/src/rocksdb/table/unique_id_impl.h

   1 //  Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
   2 //  This source code is licensed under both the GPLv2 (found in the
   3 //  COPYING file in the root directory) and Apache 2.0 License
   4 //  (found in the LICENSE.Apache file in the root directory).
   5
   6 #pragma once
   7
   8 #include <array>
   9
  10 #include "rocksdb/unique_id.h"
  11
  12 namespace ROCKSDB_NAMESPACE {
  13
  14 // Standard size unique ID, good enough for almost all practical purposes
  15 using UniqueId64x2 = std::array<uint64_t, 2>;
  16
  17 // Value never used as an actual unique ID so can be used for "null"
  18 constexpr UniqueId64x2 kNullUniqueId64x2 = {};
  19
  20 // Extended size unique ID, for extra certainty of uniqueness among SST files
  21 // spanning many hosts over a long time (rarely if ever needed)
  22 using UniqueId64x3 = std::array<uint64_t, 3>;
  23
  24 // Value never used as an actual unique ID so can be used for "null"
  25 constexpr UniqueId64x3 kNullUniqueId64x3 = {};
  26
  27 // Dynamic pointer wrapper for one of the two above
  28 struct UniqueIdPtr {
  29   uint64_t *ptr = nullptr;
  30   bool extended = false;
  31
  32   /*implicit*/ UniqueIdPtr(UniqueId64x2 *id) {
  33     ptr = (*id).data();
  34     extended = false;
  35   }
  36   /*implicit*/ UniqueIdPtr(UniqueId64x3 *id) {
  37     ptr = (*id).data();
  38     extended = true;
  39   }
  40 };
  41
  42 // Helper for GetUniqueIdFromTableProperties. This function can also be used
  43 // for temporary ids for files without sufficient information in table
  44 // properties. The internal unique id is more structured than the public
  45 // unique id, so can be manipulated in more ways but very carefully.
  46 // These must be long term stable to ensure GetUniqueIdFromTableProperties
  47 // is long term stable.
  48 Status GetSstInternalUniqueId(const std::string &db_id,
  49                               const std::string &db_session_id,
  50                               uint64_t file_number, UniqueIdPtr out,
  51                               bool force = false);
  52
  53 // Helper for GetUniqueIdFromTableProperties. External unique ids go through
  54 // this extra hashing layer so that prefixes of the unique id have predictable
  55 // "full" entropy. This hashing layer is 1-to-1 on the first 128 bits and on
  56 // the full 192 bits.
  57 // This transformation must be long term stable to ensure
  58 // GetUniqueIdFromTableProperties is long term stable.
  59 void InternalUniqueIdToExternal(UniqueIdPtr in_out);
  60
  61 // Reverse of InternalUniqueIdToExternal mostly for testing purposes
  62 // (demonstrably 1-to-1 on the first 128 bits and on the full 192 bits).
  63 void ExternalUniqueIdToInternal(UniqueIdPtr in_out);
  64
  65 // Convert numerical format to byte format for public API
  66 std::string EncodeUniqueIdBytes(UniqueIdPtr in);
  67
  68 // Reverse of EncodeUniqueIdBytes.
  69 Status DecodeUniqueIdBytes(const std::string &unique_id, UniqueIdPtr out);
  70
  71 // For presenting internal IDs for debugging purposes. Visually distinct from
  72 // UniqueIdToHumanString for external IDs.
  73 std::string InternalUniqueIdToHumanString(UniqueIdPtr in);
  74
  75 // Reformat a random value down to our "DB session id" format,
  76 // which is intended to be compact and friendly for use in file names.
  77 // `lower` is fully preserved and data is lost from `upper`.
  78 //
  79 // Detail: Encoded into 20 chars in base-36 ([0-9A-Z]), which is ~103 bits of
  80 // entropy, which is enough to expect no collisions across a billion servers
  81 // each opening DBs a million times (~2^50). Benefits vs. RFC-4122 unique id:
  82 // * Save ~ dozen bytes per SST file
  83 // * Shorter shared backup file names (some platforms have low limits)
  84 // * Visually distinct from DB id format (usually RFC-4122)
  85 std::string EncodeSessionId(uint64_t upper, uint64_t lower);
  86
  87 // Reverse of EncodeSessionId. Returns NotSupported on error rather than
  88 // Corruption because non-standard session IDs should be allowed with degraded
  89 // functionality.
  90 Status DecodeSessionId(const std::string &db_session_id, uint64_t *upper,
  91                        uint64_t *lower);
  92
  93 }  // namespace ROCKSDB_NAMESPACE