20 Memory management library [mem]

20.3 Pointer tagging [ptrtag]

20.3.1 Pointer tagging limits [ptrtag.bits]

20.3.2 Class template pointer_tag_pair [ptrtag.pair]

20.3.2.1 General [ptrtag.pair.general]

20.3.2.2 Constructors [ptrtag.pair.cons]

20.3.2.3 Support for overaligned pointers [ptrtag.pair.overalign]

20.3.2.4 Tagged pointer operations [ptrtag.pair.tagops]

20.3.2.5 Accessors [ptrtag.pair.accessors]

20.3.2.6 Swap [ptrtag.pair.swap]

20.3.2.7 Comparisons [ptrtag.pair.comp]

20.3.2.8 Tuple interface [ptrtag.pair.get]

20.3.1 Pointer tagging limits [ptrtag.bits]

🔗

inline constexpr unsigned max_pointer_bits_available = see below;

The implementation-defined limit of usable bits for pointer tagging.

Remarks: A non-zero value of max_pointer_bits_available indicates that non-arithmetic operations on invalid pointers with implementation-defined behavior ([basic.compound]) preserve sufficient information to guarantee that for an object tp of a type TP that is a specialization of tagged_pointer_pair and a pointer value q, that is a result of applying a sequence of such operations to the result of tp.tagged(), tp is equal to TP::from_tagged(q).

🔗

constexpr unsigned pointer_bits_available(size_t alignment);

Constant When: Precondition is met.

Preconditions: alignment is a power of two.

Returns: The implementation-defined number of unused bits in a pointer pointing to a hypothetical object with alignment alignment.

Recommended practice: The result is non-zero for alignment values larger than 1.

[Note 1:

On most platforms, the value is the minimum of countr_zero(alignment) and max_pointer_bits_available.

— end note]

20.3.2 Class template pointer_tag_pair [ptrtag.pair]

20.3.2.1 General [ptrtag.pair.general]

The class template pointer_tag_pair provides a type to store an object pointer together with a tag value.

🔗

namespace std { template<class U, class PtrT, unsigned BitsRequested, size_t Alignment = alignof(U)> concept tagging-compatible-pointee = // exposition only convertible_to<U*, PtrT> && pointer_bits_available(Alignment) >= BitsRequested && (is_void_v<element-of<PtrT>> || is_scalar_v<element-of<PtrT>> || is_union_v<element-of<PtrT>> || is_pointer_interconvertible_base_of_v<element-of<PtrT>, U>); template<class TagT> constexpr unsigned tag-bit-width(TagT value) noexcept; // exposition only template<class Ptr, unsigned BitsRequested = bits-available<element-of<Ptr>>, class TagT = unsigned> class pointer_tag_pair { // freestanding public: using pointer_type = Ptr; using element_type = pointer_traits<Ptr>::element_type; using tagged_pointer_type = see below; using tag_type = TagT; static constexpr unsigned bits_requested = BitsRequested; // [ptrtag.pair.cons], constructors constexpr pointer_tag_pair() noexcept; template<tagging-compatible-pointee<pointer_type, bits_requested> U> constexpr pointer_tag_pair(U* p, tag_type t); constexpr pointer_tag_pair(nullptr_t p, tag_type t); // [ptrtag.pair.overalign], support for overaligned pointers template<size_t PromisedAlignment, tagging-compatible-pointee<pointer_type, bits_requested, PromisedAlignment> U> static constexpr pointer_tag_pair from_overaligned(U* p, tag_type t); // [ptrtag.pair.tagops], tagged pointer operations tagged_pointer_type tagged_pointer() const noexcept; static pointer_tag_pair from_tagged(tagged_pointer_type p) noexcept; // [ptrtag.pair.accessors], accessors constexpr pointer_type pointer() const noexcept; constexpr tag_type tag() const noexcept; // [ptrtag.pair.swap], swap constexpr void swap(pointer_tag_pair& o) noexcept; // [ptrtag.pair.comp], comparisons friend constexpr see below operator<=>(pointer_tag_pair lhs, pointer_tag_pair rhs) noexcept requires three_way_comparable<tag_type>; friend constexpr bool operator==(pointer_tag_pair, pointer_tag_pair) noexcept requires equality_comparable<tag_type>; }; template<class Ptr> pointer_tag_pair(Ptr*) -> pointer_tag_pair<Ptr*>; template<class Ptr, class TagT> pointer_tag_pair(Ptr*, TagT tag) -> pointer_tag_pair<Ptr*, bits-available<element-of<Ptr>>, TagT>; }

An object of class pointer_tag_pair<Ptr, BitsRequested, TagT> represents a pair of pointer value of type Ptr and tag value of type TagT.

Each specialization PT of pointer_tag_pair is a trivially copyable type that models copyable such that sizeof(PT) is equal to sizeof(Ptr) and alignof(PT) is equal to alignof(Ptr).

Mandates:

(4.1)
is_same_v<remove_cvref_t<Ptr>, Ptr> is true.
(4.2)
is_same_v<remove_cvref_t<TagT>, TagT> is true.
(4.3)
is_pointer_v<Ptr> && !is_function_v<remove_pointer_t<Ptr>> is true.
(4.4)
is_unsigned_v<UT> is true, where UT is underlying_type_t<TagT> if TagT is an enumeration type, and TagT otherwise.
(4.5)
sizeof(TagT) <= sizeof(void*) is true.
(4.6)
BitsRequested <= max_pointer_bits_available is true.

🔗

template<class T> constexpr unsigned tag-bit-width(T v) noexcept;

Returns: static_cast<unsigned>(bit_width(to_underlying(v))) if is_enum_v<T> is true, otherwise static_cast<unsigned>(bit_width(v)).

20.3.2.2 Constructors [ptrtag.pair.cons]

🔗

constexpr pointer_tag_pair() noexcept;

Postconditions: pointer() is equal to nullptr and tag() is equal to TagT().

🔗

template<tagging-compatible-pointee<pointer_type, bits_requested> U>
  constexpr pointer_tag_pair(U* p, tag_type t);
constexpr pointer_tag_pair(nullptr_t p, tag_type t);

Constant When: Preconditions are met.

Preconditions:

(3.1)
p is not a pointer past the end of an object ([basic.compound]).
(3.2)
tag-bit-width(t) <= bits_requested is true.

Postconditions: pointer() is equal to p and tag() is equal to t.

Throws: Nothing.

20.3.2.3 Support for overaligned pointers [ptrtag.pair.overalign]

🔗

template<size_t PromisedAlignment,
         tagging-compatible-pointee<pointer_type, bits_requested, PromisedAlignment> U>
  static constexpr pointer_tag_pair from_overaligned(U* p, tag_type t);

Constant When: Preconditions are met.

Preconditions:

(2.1)
p is not a pointer past the end of an object ([basic.compound]).
(2.2)
p == nullptr || is_sufficiently_aligned<PromisedAlignment>(p) is true.
(2.3)
tag-bit-width(t) <= bits_requested is true.

Returns: An object ptp of type pointer_tag_pair such that both ptp.pointer() is equal to p and ptp.tag() is equal to t.

Throws: Nothing.

20.3.2.4 Tagged pointer operations [ptrtag.pair.tagops]

🔗

using tagged_pointer_type = see below;

tagged_pointer_type denotes cv void*, for cv such that pointer denotes cv U* for some type U.

🔗

tagged_pointer_type tagged_pointer() const noexcept;

Returns: An unspecified value tp of tagged_pointer_type type such that for any specialization DP of pointer_tag_pair and alignment value A for which

(2.1)
pointer_bits_available(A) >= DP::bits_requested is true,
(2.2)
is_sufficiently_aligned<A>(ptr) is true, and
(2.3)
tag-bit-width(tag) <= DP::bits_requested is true,

DP::from_tagged(tp) produces an object dp such that reinterpret_cast<pointer_type>(dp.pointer()) is equal to ptr and static_cast<TagT>(dp.tag()) is equal to tag.

[Note 1:

This function returns an invalid pointer value ([basic.compound]) with implementation-defined behavior.

— end note]

🔗

static pointer_tag_pair from_tagged(tagged_pointer_type p) noexcept;

Returns: An object dp of type pointer_tag_type, such that

(3.1)
reinterpret_cast<pointer_type>(sp.pointer()) is equal to dp.pointer() and
static_cast<TagT>(sp.tag()) is equal to dp.tag(), if p is equal to sp.tagged_pointer() for some object sp of a type that is a specialization of pointer_tag_type, such that for some alignment value A
- (3.1.1)
  pointer_bits_available(A) >= bits_requested is true,
- (3.1.2)
  is_sufficiently_aligned<A>(sp.pointer()) is true, and
- (3.1.3)
  tag-bit-width(sp.tag()) <= bits_requested is true,
(3.2)
otherwise, the values of dp.pointer() and dp.tag() are unspecified.

20.3.2.5 Accessors [ptrtag.pair.accessors]

🔗

constexpr pointer_type pointer() const noexcept;

Returns: The pointer value represented by *this.

🔗

constexpr tag_type tag() const noexcept;

Returns: The tag value represented by *this.

20.3.2.6 Swap [ptrtag.pair.swap]

🔗

constexpr void swap(pointer_tag_pair& o) noexcept;

Effects: Exchanges the values of *this and o.

20.3.2.7 Comparisons [ptrtag.pair.comp]

🔗

friend constexpr auto operator<=>(pointer_tag_pair lhs, pointer_tag_pair rhs)
  noexcept requires three_way_comparable<tag_type>;

Effects: Equivalent to: return pair(lhs.pointer(), lhs.tag()) <=> pair(rhs.pointer(), rhs.tag());

Recommended practice: Directly compare the internal bit representations if the expression lhs.tag() <=> rhs.tag() results in a call to a built-in operator <=> comparing values of type tag_type.

[Note 1:

The result of comparing unrelated pointers is unspecified.

— end note]

🔗

friend constexpr bool operator==(pointer_tag_pair lhs, pointer_tag_pair rhs)
  noexcept requires equality_comparable<tag_type>;

Effects: Equivalent to: return pair(lhs.pointer(), lhs.tag()) == pair(rhs.pointer(), rhs.tag());

Recommended practice: Directly compare the internal bit representations if the expression lhs.tag() == rhs.tag() results in a call to a built-in operator == comparing values of type tag_type.

20.3.2.8 Tuple interface [ptrtag.pair.get]

🔗

template<class Ptr, unsigned BitsRequested, class TagT>
  constexpr tuple_element_t<I, pointer_tag_pair<Ptr, BitsRequested, TagT>>
    get(pointer_tag_pair<Ptr, BitsRequested, TagT> p) noexcept;

Mandates: I < 2.

Returns:

(2.1)
p.pointer() if I is equal to zero,
(2.2)
p.tag() otherwise.