blob: 46306f35e11a77b4b94a3b32d820324103a59c49 [file]
// Copyright 2026 Google LLC
// SPDX-License-Identifier: Apache-2.0
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
#ifndef HIGHWAY_HWY_STATUS_H_
#define HIGHWAY_HWY_STATUS_H_
// Compact (8 byte) status: plain success with a 48-bit size/payload, or an
// info, warning, or error code with an optional 48-bit payload. Similar to
// absl::StatusOr<uint64_t>, but without a message and usable in constexpr
// context.
//
// Note that `ok()` is true ONLY for plain success (`Severity::kOk`), NOT for
// `kInfo` or `kWarning`. Three-way check idiom:
// - `status.ok()`: plain success (`status.size()` is valid).
// - `status.IsError()`: failure.
// - `!status.IsError()`: proceed (plain success, info, or warning), e.g. in a
// streaming loop:
// Status s = StreamStep(...);
// if (s.IsError()) return s;
// if (s.Is(kNeedInput)) { ... }
#include <stdint.h>
#if defined(HWY_HEADER_ONLY)
#include <atomic>
#endif
#include "hwy/base.h"
#if defined(HWY_HEADER_ONLY)
// Header-only inline definitions have no exporting DLL (`abort.cc` is omitted),
// so avoid `__declspec(dllimport)` on Windows; on ELF/Mach-O, keep default
// visibility even under `-fvisibility-inlines-hidden` so the dynamic linker
// coalesces `detail::ModuleCodeNameTable`'s static table across DSOs.
#if !defined(_WIN32) && (HWY_COMPILER_GCC || HWY_COMPILER_CLANG)
#define HWY_STATUS_DLLEXPORT __attribute__((visibility("default")))
#else
#define HWY_STATUS_DLLEXPORT
#endif
#else
#include "hwy/highway_export.h"
#define HWY_STATUS_DLLEXPORT HWY_DLLEXPORT
#endif
namespace hwy {
class HWY_NODISCARD_CLASS Status {
public:
// Layout of `rep_`: [62, 64) 2-bit `Severity`, [48, 62) 14-bit code ID,
// [0, 48) 48-bit payload. `Code` is the upper 16 bits (`rep_ >> 48`), which
// combines `Severity` in [14, 16) and the 14-bit ID in [0, 14) so that C++
// enum auto-increment preserves the severity bits. Invariant: the ID is zero
// iff the severity is `kOk`.
enum class Severity : uint8_t {
kOk = 0, // Plain success with 48-bit size/payload; code ID is 0.
kInfo = 1, // Informational (e.g. "need more input") + code + payload.
kWarning = 2, // Non-fatal warning + code + payload.
kError = 3 // Error + code + payload.
};
using Code = uint16_t;
static constexpr uint64_t kPayloadBits = 48;
static constexpr uint64_t kIdBits = 14;
static constexpr uint64_t kSeverityShift = kPayloadBits + kIdBits; // 62
static constexpr uint64_t kMaxPayload = (uint64_t{1} << kPayloadBits) - 1;
static constexpr Code kMaxCode = (Code{1} << kIdBits) - 1; // 0x3FFF
// Note: any `enum` with underlying type `uint16_t` (`Status::Code`) satisfies
// this check; using `: Status::Code` only for status enums is a convention,
// not a guarantee.
template <typename Enum>
static constexpr bool IsStatusEnum() {
return IsEnum<Enum>() && IsSame<UnderlyingType<Enum>, Code>();
}
// Code ID ranges within each severity (the same ranges apply to info,
// warning and error codes):
// - [1, kFirstModuleCode): general codes that apply to any module; the names
// below are modeled on absl::StatusCode and known to `GeneralCodeName`.
// - [kFirstModuleCode, kFirstAppCode): Highway modules, each owning
// `kCodesPerModule` IDs starting at `ModuleBegin(Module)`. Modules can
// register a `CodeNameFunc` via `SetModuleCodeNameFunc` so `CodeName` can
// resolve their code names.
// - [kFirstAppCode, kMaxCode]: applications.
static constexpr Code kFirstModuleCode = 256;
static constexpr Code kCodesPerModule = 256;
static constexpr Code kFirstAppCode = 4096;
static constexpr Code kNumModules =
(kFirstAppCode - kFirstModuleCode) / kCodesPerModule; // 15
// Registry of Highway modules that define status codes. Append new modules;
// the numeric values are stable.
enum class Module : uint8_t {
kIO = 0, // hwy/io/file.h (`IOCode`)
kReserved0 = 1, // Reserved for a future module.
};
// Combines `severity` and a 14-bit `id` into a 16-bit `Code`. Note that
// enum auto-increment past `kMaxCode` would change the severity; this cannot
// happen for module or application codes that stay within their range.
static constexpr Code MakeCode(Severity severity, Code id) {
return static_cast<Code>((static_cast<Code>(severity) << kIdBits) |
(id & kMaxCode));
}
// First ID of `module`'s range.
static constexpr Code ModuleBegin(Module module) {
return static_cast<Code>(kFirstModuleCode +
static_cast<Code>(module) * kCodesPerModule);
}
// Defining a module or application enum as `enum class MyCode :
// hwy::Status::Code` whose first enumerator is one of these enables implicit
// construction of `Status` with that severity, e.g.
// `kNeedInput = Status::FirstInfo(Status::kFirstAppCode)`, or
// `kWrongMode = Status::ModuleError(Status::Module::kIO)`.
static HWY_CXX14_CONSTEXPR Code FirstInfo(Code base_id) {
HWY_DASSERT(base_id != 0 && base_id <= kMaxCode);
return MakeCode(Severity::kInfo, base_id);
}
static HWY_CXX14_CONSTEXPR Code FirstWarning(Code base_id) {
HWY_DASSERT(base_id != 0 && base_id <= kMaxCode);
return MakeCode(Severity::kWarning, base_id);
}
static HWY_CXX14_CONSTEXPR Code FirstError(Code base_id) {
HWY_DASSERT(base_id != 0 && base_id <= kMaxCode);
return MakeCode(Severity::kError, base_id);
}
static HWY_CXX14_CONSTEXPR Code ModuleInfo(Module module) {
return FirstInfo(ModuleBegin(module));
}
static HWY_CXX14_CONSTEXPR Code ModuleWarning(Module module) {
return FirstWarning(ModuleBegin(module));
}
static HWY_CXX14_CONSTEXPR Code ModuleError(Module module) {
return FirstError(ModuleBegin(module));
}
enum GeneralCode : Code {
kOk = 0,
kUnknown = (static_cast<Code>(Severity::kError) << kIdBits) | 1,
kCancelled,
kArgument, // invalid argument
kTimeout, // deadline exceeded / timed out
kNotFound,
kPermission, // permission denied, e.g. file system or RPC access
kResource, // out of memory, disk space, file descriptors
kPrecondition, // failed precondition, e.g. not opened, or in use
kRange, // out of range
kUnimplemented, // e.g. backend lacks the feature
kInternal, // bug, please report
kUnavailable, // transient, retry may succeed
kDataLoss, // corrupt data
kTruncated, // input shorter than expected, e.g. read past EOF
kOSError // other OS error; payload is errno or GetLastError
};
// Default is plain success with size/payload 0.
constexpr Status() : rep_(0) {}
// Plain success with `size` bytes. Constrained to non-bool integers so that
// booleans and enums without `: Status::Code` do not silently convert to a
// size. Payloads above 2^48 - 1 (`kMaxPayload`) assert in debug builds and
// saturate in release builds.
template <typename T, EnableIf<IsInteger<T>() &&
!IsSame<RemoveCvRef<T>, bool>()>* = nullptr>
explicit HWY_CXX14_CONSTEXPR Status(T size)
: rep_(ClampPayload(static_cast<uint64_t>(size))) {
// Also rejects negative signed values, which wrap above kMaxPayload.
HWY_DASSERT(static_cast<uint64_t>(size) <= kMaxPayload);
}
static constexpr Status Ok() { return Status(); }
template <typename T, EnableIf<IsInteger<T>() &&
!IsSame<RemoveCvRef<T>, bool>()>* = nullptr>
static HWY_CXX14_CONSTEXPR Status Ok(T size) {
return Status(size);
}
// Implicit from `GeneralCode` and from any module or application enum (scoped
// or unscoped) whose underlying type is `Status::Code`, with an optional
// payload (payloads above 2^48 - 1 saturate). `kOk` (0) yields plain success.
// Debug builds check the invariant that nonzero codes have a non-`kOk`
// severity.
template <typename Enum, EnableIf<IsStatusEnum<Enum>()>* = nullptr>
HWY_CXX14_CONSTEXPR Status(Enum code, uint64_t payload = 0) // NOLINT
: rep_((static_cast<uint64_t>(static_cast<Code>(code)) << kPayloadBits) |
ClampPayload(payload)) {
HWY_DASSERT(IsValidCode(static_cast<Code>(code)));
}
// Explicit factories that set the severity (overriding any severity bits in
// `code` so raw 14-bit IDs or `GeneralCode`s can be used with any severity).
// `code` must have a nonzero ID.
static HWY_CXX14_CONSTEXPR Status Info(Code code, uint64_t payload = 0) {
HWY_DASSERT((code & kMaxCode) != 0);
return Status(RawTag(), MakeRep(Severity::kInfo, code, payload));
}
template <typename Enum, EnableIf<IsStatusEnum<Enum>()>* = nullptr>
static HWY_CXX14_CONSTEXPR Status Info(Enum code, uint64_t payload = 0) {
return Info(static_cast<Code>(code), payload);
}
static HWY_CXX14_CONSTEXPR Status Warning(Code code, uint64_t payload = 0) {
HWY_DASSERT((code & kMaxCode) != 0);
return Status(RawTag(), MakeRep(Severity::kWarning, code, payload));
}
template <typename Enum, EnableIf<IsStatusEnum<Enum>()>* = nullptr>
static HWY_CXX14_CONSTEXPR Status Warning(Enum code, uint64_t payload = 0) {
return Warning(static_cast<Code>(code), payload);
}
static HWY_CXX14_CONSTEXPR Status Error(Code code, uint64_t payload = 0) {
HWY_DASSERT((code & kMaxCode) != 0);
return Status(RawTag(), MakeRep(Severity::kError, code, payload));
}
template <typename Enum, EnableIf<IsStatusEnum<Enum>()>* = nullptr>
static HWY_CXX14_CONSTEXPR Status Error(Enum code, uint64_t payload = 0) {
return Error(static_cast<Code>(code), payload);
}
// True iff plain success (`Severity::kOk` and code 0; no error, warning, or
// info).
constexpr bool ok() const { return rep_ <= kMaxPayload; }
constexpr Severity severity() const {
return static_cast<Severity>(rep_ >> kSeverityShift);
}
constexpr bool IsInfo() const { return severity() == Severity::kInfo; }
constexpr bool IsWarning() const { return severity() == Severity::kWarning; }
constexpr bool IsError() const { return severity() == Severity::kError; }
// Full 16-bit code including the 2-bit severity, for comparing or switching
// against `GeneralCode` and module/app enums. Returns `kOk` (0) when `ok()`.
constexpr Code code() const {
return static_cast<Code>(rep_ >> kPayloadBits);
}
// 14-bit code ID without the severity bits.
constexpr Code id() const {
return static_cast<Code>((rep_ >> kPayloadBits) & kMaxCode);
}
// True iff `code()` equals `code` (severity and ID), ignoring the payload.
// Accepts `GeneralCode` and module/app enums, including scoped ones.
template <typename Enum, EnableIf<IsStatusEnum<Enum>()>* = nullptr>
constexpr bool Is(Enum code) const {
return this->code() == static_cast<Code>(code);
}
// Returns the 48-bit size for plain success (`ok()`). Debug builds assert
// `ok()`; release builds still mask via `payload()` so non-`ok()` statuses
// (e.g. `kInfo`/`kWarning` after `!IsError()`) never leak the upper 16
// severity/code bits into a size calculation.
HWY_CXX14_CONSTEXPR uint64_t size() const {
HWY_DASSERT(ok());
return payload();
}
// Valid for any status; typically a size for `ok()`, or OS/context details
// for info, warnings, and errors (e.g. errno or byte offset).
constexpr uint64_t payload() const { return rep_ & kMaxPayload; }
// Returns the name of a general code (regardless of its severity), or
// nullptr if `code` is not a `GeneralCode`.
static constexpr const char* GeneralCodeName(Code code) {
return (code & kMaxCode) == 0 ? "kOk"
: MakeCode(Severity::kError, code) == kUnknown ? "kUnknown"
: MakeCode(Severity::kError, code) == kCancelled ? "kCancelled"
: MakeCode(Severity::kError, code) == kArgument ? "kArgument"
: MakeCode(Severity::kError, code) == kTimeout ? "kTimeout"
: MakeCode(Severity::kError, code) == kNotFound ? "kNotFound"
: MakeCode(Severity::kError, code) == kPermission ? "kPermission"
: MakeCode(Severity::kError, code) == kResource ? "kResource"
: MakeCode(Severity::kError, code) == kPrecondition ? "kPrecondition"
: MakeCode(Severity::kError, code) == kRange ? "kRange"
: MakeCode(Severity::kError, code) == kUnimplemented
? "kUnimplemented"
: MakeCode(Severity::kError, code) == kInternal ? "kInternal"
: MakeCode(Severity::kError, code) == kUnavailable ? "kUnavailable"
: MakeCode(Severity::kError, code) == kDataLoss ? "kDataLoss"
: MakeCode(Severity::kError, code) == kTruncated ? "kTruncated"
: MakeCode(Severity::kError, code) == kOSError ? "kOSError"
: nullptr;
}
// Per-module callback returning the name of `code` (or nullptr if unknown).
using CodeNameFunc = const char* (*)(Code code);
// Registers `func` to resolve code names for `module`, returning the previous
// function (or nullptr). Thread-safe.
static HWY_STATUS_DLLEXPORT CodeNameFunc
SetModuleCodeNameFunc(Module module, CodeNameFunc func);
// Returns the name of a general code or registered module code (regardless of
// its severity), or "(module/app code)" otherwise.
static HWY_STATUS_DLLEXPORT const char* CodeName(Code code);
template <typename Enum, EnableIf<IsStatusEnum<Enum>()>* = nullptr>
static const char* CodeName(Enum code) {
return CodeName(static_cast<Code>(code));
}
const char* Name() const { return CodeName(code()); }
// Compares the entire representation including payload.
friend constexpr bool operator==(Status a, Status b) {
return a.rep_ == b.rep_;
}
friend constexpr bool operator!=(Status a, Status b) {
return a.rep_ != b.rep_;
}
// Prevent `status == kCode`, which would implicitly construct
// `Status(kCode, 0)` and fail whenever `status` has a nonzero payload (e.g.
// errno). Use `status.Is(kCode)` to ignore the payload, or
// `status == Status(kCode, payload)` to compare both.
template <typename Enum>
friend If<IsStatusEnum<Enum>(), bool, void> operator==(Status, Enum) = delete;
template <typename Enum>
friend If<IsStatusEnum<Enum>(), bool, void> operator!=(Status, Enum) = delete;
template <typename Enum>
friend If<IsStatusEnum<Enum>(), bool, void> operator==(Enum, Status) = delete;
template <typename Enum>
friend If<IsStatusEnum<Enum>(), bool, void> operator!=(Enum, Status) = delete;
private:
struct RawTag {};
// The ID is zero iff the severity is kOk.
static constexpr bool IsValidCode(Code code) {
return ((code & kMaxCode) == 0) == ((code >> kIdBits) == 0);
}
static constexpr uint64_t MakeRep(Severity severity, Code code,
uint64_t payload) {
return (static_cast<uint64_t>(MakeCode(severity, code)) << kPayloadBits) |
ClampPayload(payload);
}
// Payloads above 2^48 - 1 saturate to `kMaxPayload`.
static constexpr uint64_t ClampPayload(uint64_t payload) {
return payload <= kMaxPayload ? payload : kMaxPayload;
}
constexpr Status(RawTag /*tag*/, uint64_t rep) : rep_(rep) {}
uint64_t rep_;
};
static_assert(sizeof(Status) == 8, "Status must be 8 bytes");
#if defined(HWY_HEADER_ONLY)
namespace detail {
HWY_STATUS_DLLEXPORT inline std::atomic<Status::CodeNameFunc>*
ModuleCodeNameTable() {
static std::atomic<Status::CodeNameFunc> table[Status::kNumModules] = {};
return table;
}
} // namespace detail
HWY_STATUS_DLLEXPORT inline Status::CodeNameFunc Status::SetModuleCodeNameFunc(
Module module, CodeNameFunc func) {
const size_t idx = static_cast<size_t>(module);
if (idx >= kNumModules) return nullptr;
return detail::ModuleCodeNameTable()[idx].exchange(func,
std::memory_order_acq_rel);
}
HWY_STATUS_DLLEXPORT inline const char* Status::CodeName(Code code) {
const char* general = GeneralCodeName(code);
if (general != nullptr) return general;
const Code id = static_cast<Code>(code & kMaxCode);
if (id >= kFirstModuleCode && id < kFirstAppCode) {
const size_t idx =
static_cast<size_t>(id - kFirstModuleCode) / size_t{kCodesPerModule};
const CodeNameFunc func =
detail::ModuleCodeNameTable()[idx].load(std::memory_order_acquire);
if (func != nullptr) {
const char* name = func(code);
if (name != nullptr) return name;
}
}
return "(module/app code)";
}
#endif // HWY_HEADER_ONLY
} // namespace hwy
#undef HWY_STATUS_DLLEXPORT
#endif // HIGHWAY_HWY_STATUS_H_