tor-browser

ColumnNumber.h (13161B)

---

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */

// [SMDOC] Column numbers
//
// Inside SpiderMonkey, column numbers are represented as 1-origin 32-bit
// unsigned integers. Some parts of the engine use the highest bit of a column
// number as a tag to indicate Wasm frame.
//
// These classes help clarifying the origin of the column number, and also
// figuring out whether the column number uses the wasm's tag or not, and also
// help converting between them.
//
// Also these classes support converting from 0-origin column number.
//
// In a 0-origin context, column 0 is the first character of the line.
// In a 1-origin context, column 1 is the first character of the line,
// for example:
//
//           function foo() { ... }
//           ^              ^
// 0-origin: 0              15
// 1-origin: 1              16

#ifndef js_ColumnNumber_h
#define js_ColumnNumber_h

#include "mozilla/Assertions.h"  // MOZ_ASSERT
#include "mozilla/Attributes.h"  // MOZ_IMPLICIT

#include <limits>    // std::numeric_limits
#include <stdint.h>  // uint32_t

namespace JS {

// Wasm function index.
//
// This class is used as parameter or return type of
// TaggedColumnNumberOneOrigin class below.
struct WasmFunctionIndex {
 // TaggedColumnNumberOneOrigin uses the highest bit as a tag.
 static constexpr uint32_t Limit = std::numeric_limits<int32_t>::max() / 2;

 // For wasm frames, the function index is returned as the column with the
 // high bit set. In paths that format error stacks into strings, this
 // information can be used to synthesize a proper wasm frame. But when raw
 // column numbers are handed out, we just fix them to the first column to
 // avoid confusion.
 static constexpr uint32_t DefaultBinarySourceColumnNumberOneOrigin = 1;

private:
 uint32_t value_ = 0;

public:
 constexpr WasmFunctionIndex() = default;
 constexpr WasmFunctionIndex(const WasmFunctionIndex& other) = default;

 inline explicit WasmFunctionIndex(uint32_t value) : value_(value) {
   MOZ_ASSERT(valid());
 }

 uint32_t value() const { return value_; }

 bool valid() const { return value_ <= Limit; }
};

// The offset between 2 column numbers.
struct ColumnNumberOffset {
private:
 int32_t value_ = 0;

public:
 constexpr ColumnNumberOffset() = default;
 constexpr ColumnNumberOffset(const ColumnNumberOffset& other) = default;

 inline explicit ColumnNumberOffset(int32_t value) : value_(value) {}

 static constexpr ColumnNumberOffset zero() { return ColumnNumberOffset(); }

 bool operator==(const ColumnNumberOffset& rhs) const {
   return value_ == rhs.value_;
 }

 bool operator!=(const ColumnNumberOffset& rhs) const {
   return !(*this == rhs);
 }

 int32_t value() const { return value_; }
};

// The positive offset from certain column number.
struct ColumnNumberUnsignedOffset {
private:
 uint32_t value_ = 0;

public:
 constexpr ColumnNumberUnsignedOffset() = default;
 constexpr ColumnNumberUnsignedOffset(
     const ColumnNumberUnsignedOffset& other) = default;

 inline explicit ColumnNumberUnsignedOffset(uint32_t value) : value_(value) {}

 static constexpr ColumnNumberUnsignedOffset zero() {
   return ColumnNumberUnsignedOffset();
 }

 ColumnNumberUnsignedOffset operator+(
     const ColumnNumberUnsignedOffset& offset) const {
   return ColumnNumberUnsignedOffset(value_ + offset.value());
 }

 ColumnNumberUnsignedOffset& operator+=(
     const ColumnNumberUnsignedOffset& offset) {
   value_ += offset.value();
   return *this;
 }

 bool operator==(const ColumnNumberUnsignedOffset& rhs) const {
   return value_ == rhs.value_;
 }

 bool operator!=(const ColumnNumberUnsignedOffset& rhs) const {
   return !(*this == rhs);
 }

 uint32_t value() const { return value_; }

 uint32_t* addressOfValueForTranscode() { return &value_; }
};

struct TaggedColumnNumberOneOrigin;

namespace detail {

// Shared implementation of {,Limited}ColumnNumberOneOrigin classes.
//
// LimitValue being 0 means there's no limit.
template <uint32_t LimitValue = 0>
struct MaybeLimitedColumnNumber {
public:
 static constexpr uint32_t OriginValue = 1;

protected:
 uint32_t value_ = OriginValue;

 friend struct ::JS::TaggedColumnNumberOneOrigin;

public:
 constexpr MaybeLimitedColumnNumber() = default;
 MaybeLimitedColumnNumber(const MaybeLimitedColumnNumber& other) = default;
 MaybeLimitedColumnNumber& operator=(const MaybeLimitedColumnNumber& other) =
     default;

 explicit MaybeLimitedColumnNumber(uint32_t value) : value_(value) {
   MOZ_ASSERT(valid());
 }

 bool operator==(const MaybeLimitedColumnNumber<LimitValue>& rhs) const {
   return value_ == rhs.value_;
 }

 bool operator!=(const MaybeLimitedColumnNumber<LimitValue>& rhs) const {
   return !(*this == rhs);
 }

 MaybeLimitedColumnNumber<LimitValue> operator+(
     const ColumnNumberOffset& offset) const {
   MOZ_ASSERT(valid());
   MOZ_ASSERT(ptrdiff_t(value_) + offset.value() >= 0);
   return MaybeLimitedColumnNumber<LimitValue>(value_ + offset.value());
 }

 MaybeLimitedColumnNumber<LimitValue> operator+(
     const ColumnNumberUnsignedOffset& offset) const {
   MOZ_ASSERT(valid());
   MOZ_ASSERT(ptrdiff_t(value_) + offset.value() >= 0);
   return MaybeLimitedColumnNumber<LimitValue>(value_ + offset.value());
 }

 MaybeLimitedColumnNumber<LimitValue> operator-(
     const ColumnNumberOffset& offset) const {
   MOZ_ASSERT(valid());
   MOZ_ASSERT(ptrdiff_t(value_) - offset.value() >= 0);
   return MaybeLimitedColumnNumber<LimitValue>(value_ - offset.value());
 }
 ColumnNumberOffset operator-(
     const MaybeLimitedColumnNumber<LimitValue>& other) const {
   MOZ_ASSERT(valid());
   return ColumnNumberOffset(int32_t(value_) - int32_t(other.value_));
 }

 MaybeLimitedColumnNumber<LimitValue>& operator+=(
     const ColumnNumberOffset& offset) {
   MOZ_ASSERT(valid());
   MOZ_ASSERT(ptrdiff_t(value_) + offset.value() >= 0);
   value_ += offset.value();
   MOZ_ASSERT(valid());
   return *this;
 }
 MaybeLimitedColumnNumber<LimitValue>& operator-=(
     const ColumnNumberOffset& offset) {
   MOZ_ASSERT(valid());
   MOZ_ASSERT(ptrdiff_t(value_) - offset.value() >= 0);
   value_ -= offset.value();
   MOZ_ASSERT(valid());
   return *this;
 }

 bool operator<(const MaybeLimitedColumnNumber<LimitValue>& rhs) const {
   MOZ_ASSERT(valid());
   MOZ_ASSERT(rhs.valid());
   return value_ < rhs.value_;
 }
 bool operator<=(const MaybeLimitedColumnNumber<LimitValue>& rhs) const {
   MOZ_ASSERT(valid());
   MOZ_ASSERT(rhs.valid());
   return value_ <= rhs.value_;
 }
 bool operator>(const MaybeLimitedColumnNumber<LimitValue>& rhs) const {
   MOZ_ASSERT(valid());
   MOZ_ASSERT(rhs.valid());
   return value_ > rhs.value_;
 }
 bool operator>=(const MaybeLimitedColumnNumber<LimitValue>& rhs) const {
   MOZ_ASSERT(valid());
   MOZ_ASSERT(rhs.valid());
   return value_ >= rhs.value_;
 }

 uint32_t oneOriginValue() const {
   MOZ_ASSERT(valid());

   return value_;
 }

 uint32_t* addressOfValueForTranscode() { return &value_; }

 bool valid() const {
   if constexpr (LimitValue == 0) {
     return true;
   }

   MOZ_ASSERT(value_ != 0);

   return value_ <= LimitValue;
 }
};

// See the comment for LimitedColumnNumberOneOrigin below
static constexpr uint32_t ColumnNumberOneOriginLimit =
   std::numeric_limits<int32_t>::max() / 2;

}  // namespace detail

// Column number in 1-origin with 31-bit limit.
//
// Various parts of the engine requires the column number be represented in
// 31 bits.
//
// See:
//  * TaggedColumnNumberOneOrigin
//  * TokenStreamAnyChars::checkOptions
//  * SourceNotes::isRepresentable
//  * WasmFrameIter::computeLine
struct LimitedColumnNumberOneOrigin : public detail::MaybeLimitedColumnNumber<
                                         detail::ColumnNumberOneOriginLimit> {
private:
 using Base =
     detail::MaybeLimitedColumnNumber<detail::ColumnNumberOneOriginLimit>;

public:
 static constexpr uint32_t Limit = detail::ColumnNumberOneOriginLimit;

 static_assert(uint32_t(Limit + Limit) > Limit,
               "Adding Limit should not overflow");

 using Base::Base;

 LimitedColumnNumberOneOrigin() = default;
 LimitedColumnNumberOneOrigin(const LimitedColumnNumberOneOrigin& other) =
     default;
 MOZ_IMPLICIT LimitedColumnNumberOneOrigin(const Base& other) : Base(other) {}

 static LimitedColumnNumberOneOrigin limit() {
   return LimitedColumnNumberOneOrigin(Limit);
 }

 static LimitedColumnNumberOneOrigin fromUnlimited(uint32_t value) {
   if (value > Limit) {
     return LimitedColumnNumberOneOrigin(Limit);
   }
   return LimitedColumnNumberOneOrigin(value);
 }
 static LimitedColumnNumberOneOrigin fromUnlimited(
     const MaybeLimitedColumnNumber<0>& value) {
   return fromUnlimited(value.oneOriginValue());
 }

 static LimitedColumnNumberOneOrigin fromZeroOrigin(uint32_t value) {
   return LimitedColumnNumberOneOrigin(value + 1);
 }
};

// Column number in 1-origin.
struct ColumnNumberOneOrigin : public detail::MaybeLimitedColumnNumber<0> {
private:
 using Base = detail::MaybeLimitedColumnNumber<0>;

public:
 using Base::Base;
 using Base::operator=;

 ColumnNumberOneOrigin() = default;
 ColumnNumberOneOrigin(const ColumnNumberOneOrigin& other) = default;
 ColumnNumberOneOrigin& operator=(ColumnNumberOneOrigin&) = default;

 MOZ_IMPLICIT ColumnNumberOneOrigin(const Base& other) : Base(other) {}

 explicit ColumnNumberOneOrigin(const LimitedColumnNumberOneOrigin& other)
     : Base(other.oneOriginValue()) {}

 static ColumnNumberOneOrigin fromZeroOrigin(uint32_t value) {
   return ColumnNumberOneOrigin(value + 1);
 }
};

// Either LimitedColumnNumberOneOrigin, or WasmFunctionIndex.
//
// In order to pass the Wasm frame's (url, bytecode-offset, func-index) tuple
// through the existing (url, line, column) tuple, it tags the highest bit of
// the column to indicate "this is a wasm frame".
//
// When knowing clients see this bit, they shall render the tuple
// (url, line, column|bit) as "url:wasm-function[column]:0xline" according
// to the WebAssembly Web API's Developer-Facing Display Conventions.
//   https://webassembly.github.io/spec/web-api/index.html#conventions
// The wasm bytecode offset continues to be passed as the JS line to avoid
// breaking existing devtools code written when this used to be the case.
//
// 0b0YYYYYYY_YYYYYYYY_YYYYYYYY_YYYYYYYY LimitedColumnNumberOneOrigin
// 0b1YYYYYYY_YYYYYYYY_YYYYYYYY_YYYYYYYY WasmFunctionIndex
//
// The tagged colum number shouldn't escape the JS engine except for the
// following places:
//   * SavedFrame API which can directly access WASM frame's info
//   * ubi::Node API which can also directly access WASM frame's info
struct TaggedColumnNumberOneOrigin {
 static constexpr uint32_t WasmFunctionTag = 1u << 31;

 static_assert((WasmFunctionIndex::Limit & WasmFunctionTag) == 0);
 static_assert((LimitedColumnNumberOneOrigin::Limit & WasmFunctionTag) == 0);

protected:
 uint32_t value_ = LimitedColumnNumberOneOrigin::OriginValue;

 explicit TaggedColumnNumberOneOrigin(uint32_t value) : value_(value) {}

public:
 constexpr TaggedColumnNumberOneOrigin() = default;
 TaggedColumnNumberOneOrigin(const TaggedColumnNumberOneOrigin& other) =
     default;

 explicit TaggedColumnNumberOneOrigin(
     const LimitedColumnNumberOneOrigin& other)
     : value_(other.value_) {
   MOZ_ASSERT(isLimitedColumnNumber());
 }
 explicit TaggedColumnNumberOneOrigin(const WasmFunctionIndex& other)
     : value_(other.value() | WasmFunctionTag) {
   MOZ_ASSERT(isWasmFunctionIndex());
 }

 static TaggedColumnNumberOneOrigin fromRaw(uint32_t value) {
   return TaggedColumnNumberOneOrigin(value);
 }

 static TaggedColumnNumberOneOrigin forDifferentialTesting() {
   return TaggedColumnNumberOneOrigin(LimitedColumnNumberOneOrigin());
 }

 bool operator==(const TaggedColumnNumberOneOrigin& rhs) const {
   return value_ == rhs.value_;
 }

 bool operator!=(const TaggedColumnNumberOneOrigin& rhs) const {
   return !(*this == rhs);
 }

 bool isLimitedColumnNumber() const { return !isWasmFunctionIndex(); }

 bool isWasmFunctionIndex() const { return !!(value_ & WasmFunctionTag); }

 LimitedColumnNumberOneOrigin toLimitedColumnNumber() const {
   MOZ_ASSERT(isLimitedColumnNumber());
   return LimitedColumnNumberOneOrigin(value_);
 }

 WasmFunctionIndex toWasmFunctionIndex() const {
   MOZ_ASSERT(isWasmFunctionIndex());
   return WasmFunctionIndex(value_ & ~WasmFunctionTag);
 }

 uint32_t oneOriginValue() const {
   return isWasmFunctionIndex()
              ? WasmFunctionIndex::DefaultBinarySourceColumnNumberOneOrigin
              : toLimitedColumnNumber().oneOriginValue();
 }

 uint32_t rawValue() const { return value_; }

 uint32_t* addressOfValueForTranscode() { return &value_; }
};

}  // namespace JS

#endif /* js_ColumnNumber_h */