@delali/narsil-react-native 0.0.0-stage → 0.3.1-next.151

package/cpp/AttachedField.cpp

@@ -0,0 +1,234 @@
+#include "AttachedField.hpp"
+#include "HostMemory.hpp"
+
+#include <cmath>
+#include <string>
+
+namespace margelo::nitro::narsil {
+
+namespace {
+
+struct Region {
+  uint8_t* bytes;
+  size_t elements;
+};
+
+Region heldRegion(const MemoryView& view, size_t elementBytes, std::vector<std::shared_ptr<ArrayBuffer>>& held,
+                  const char* what) {
+  if (!isHostOwned(view.buffer)) {
+    throwInvalid(std::string(what) + " lies outside the memory that this module allocated");
+  }
+  uint8_t* bytes = bytesWithin(view.buffer, view.byteOffset, view.byteLength, what);
+  if (bytes == nullptr || reinterpret_cast<uintptr_t>(bytes) % elementBytes != 0 ||
+      static_cast<size_t>(view.byteLength) % elementBytes != 0) {
+    throwInvalid(std::string(what) + " is empty or misaligned");
+  }
+  held.push_back(view.buffer);
+  return Region{bytes, static_cast<size_t>(view.byteLength) / elementBytes};
+}
+
+uint32_t wholeCount(double value, const char* what) {
+  if (!std::isfinite(value) || value < 0 || value > UINT32_MAX || std::floor(value) != value) {
+    throwInvalid(std::string(what) + " must be a whole number from 0 to 4294967295");
+  }
+  return static_cast<uint32_t>(value);
+}
+
+int32_t headerWord(const int32_t* words, uint32_t index) { return __atomic_load_n(words + index, __ATOMIC_SEQ_CST); }
+
+bool covers(size_t length, uint64_t required) { return static_cast<uint64_t>(length) >= required; }
+
+void rememberWake(void* context, int32_t ordinal) {
+  auto* wakes = static_cast<PendingWakes*>(context);
+  if (wakes->count >= WAKES_KEPT_PER_CALL) return;
+  wakes->ordinals[wakes->count] = ordinal;
+  wakes->count += 1;
+}
+
+uint64_t bytesInUse(uint64_t slots, uint64_t entriesPerBlock, uint64_t entryBytes, uint32_t index) {
+  uint64_t first = static_cast<uint64_t>(index) * entriesPerBlock;
+  if (first >= slots) return 0;
+  uint64_t remaining = slots - first;
+  return (remaining < entriesPerBlock ? remaining : entriesPerBlock) * entryBytes;
+}
+
+template <typename Pointer>
+void readBlocks(const std::vector<MemoryView>& views, uint64_t slots, uint64_t entriesPerBlock, uint64_t entryBytes,
+                size_t alignment, std::vector<std::shared_ptr<ArrayBuffer>>& held, std::vector<Pointer>& out,
+                const char* what) {
+  out.assign(views.size(), nullptr);
+  for (size_t index = 0; index < views.size(); index++) {
+    const MemoryView& view = views[index];
+    if (view.byteLength == 0) continue;
+    Region region = heldRegion(view, 1, held, what);
+    if (reinterpret_cast<uintptr_t>(region.bytes) % alignment != 0 ||
+        !covers(region.elements, bytesInUse(slots, entriesPerBlock, entryBytes, static_cast<uint32_t>(index)))) {
+      throwInvalid(std::string(what) + " is misaligned or smaller than the records it holds");
+    }
+    out[index] = reinterpret_cast<Pointer>(region.bytes);
+  }
+}
+
+}
+
+HybridNarsilAttachedGraphImpl::HybridNarsilAttachedGraphImpl(const GraphMemory& memory) : HybridObject(TAG) {
+  Region header = heldRegion(memory.graphHeader, sizeof(int32_t), _held, "The graph header");
+  if (header.elements < NARSIL_GRAPH_HEADER_WORDS) throwInvalid("The graph header is too short");
+  Region levels = heldRegion(memory.nodeLevels, 1, _held, "The node levels");
+  Region level0 = heldRegion(memory.level0, sizeof(int32_t), _held, "The base layer");
+  Region upperBase = heldRegion(memory.upperBase, sizeof(int32_t), _held, "The upper layer starts");
+  Region upper = heldRegion(memory.upper, sizeof(int32_t), _held, "The upper layers");
+  Region locks = heldRegion(memory.locks, sizeof(int32_t), _held, "The node locks");
+  Region tombstones = heldRegion(memory.tombstones, 1, _held, "The tombstones");
+  Region incoming = heldRegion(memory.incoming, sizeof(int32_t), _held, "The incoming counts");
+  Region due = heldRegion(memory.nearestLinkDue, 1, _held, "The nearest link flags");
+  Region heldLocks = heldRegion(memory.heldLocks, sizeof(int32_t), _held, "The held locks");
+  graph.header = reinterpret_cast<int32_t*>(header.bytes);
+  graph.node_levels = levels.bytes;
+  graph.level0 = reinterpret_cast<int32_t*>(level0.bytes);
+  graph.upper_base = reinterpret_cast<int32_t*>(upperBase.bytes);
+  graph.upper = reinterpret_cast<int32_t*>(upper.bytes);
+  graph.locks = reinterpret_cast<int32_t*>(locks.bytes);
+  graph.tombstones = tombstones.bytes;
+  graph.incoming = reinterpret_cast<int32_t*>(incoming.bytes);
+  graph.nearest_link_due = due.bytes;
+  graph.held_locks = reinterpret_cast<int32_t*>(heldLocks.bytes);
+  size_t threadSlots = heldLocks.elements / NARSIL_HELD_WORDS_PER_THREAD;
+  graph.thread_slots = threadSlots > UINT32_MAX ? UINT32_MAX : static_cast<uint32_t>(threadSlots);
+  if (graph.thread_slots == 0) throwInvalid("The held locks hold no thread slot");
+  int32_t slots = headerWord(graph.header, NARSIL_GRAPH_WORD_SLOTS);
+  int32_t upperUsed = headerWord(graph.header, NARSIL_GRAPH_WORD_UPPER_USED);
+  int32_t maxBaseNeighbours = headerWord(graph.header, NARSIL_GRAPH_WORD_MMAX0);
+  if (slots < 0 || upperUsed < 0 || maxBaseNeighbours <= 0) throwInvalid("The graph header is inconsistent");
+  uint64_t ordinals = static_cast<uint64_t>(slots);
+  uint64_t baseStride = static_cast<uint64_t>(maxBaseNeighbours) + NARSIL_LIST_WORDS_OVER_NEIGHBOURS;
+  if (!covers(levels.elements, ordinals) || !covers(level0.elements, ordinals * baseStride) ||
+      !covers(upperBase.elements, ordinals) || !covers(locks.elements, ordinals) ||
+      !covers(tombstones.elements, ordinals) || !covers(incoming.elements, ordinals) ||
+      !covers(due.elements, ordinals) || !covers(upper.elements, static_cast<uint64_t>(upperUsed))) {
+    throwInvalid("The graph regions are smaller than the graph they hold");
+  }
+  graph.wake = rememberWake;
+  graph.wake_context = &wakes;
+}
+
+HybridNarsilAttachedStoreImpl::HybridNarsilAttachedStoreImpl(const StoreMemory& memory) : HybridObject(TAG) {
+  store.dimension = wholeCount(memory.dimension, "The dimension");
+  store.bits = wholeCount(memory.bits, "The code bits");
+  store.records_per_block = wholeCount(memory.recordsPerBlock, "The records per block");
+  store.vectors_per_block = wholeCount(memory.vectorsPerBlock, "The vectors per block");
+  uint32_t strideBytes = wholeCount(memory.vectorStrideBytes, "The vector stride");
+  if (store.dimension == 0 || strideBytes % sizeof(float) != 0) throwInvalid("The vector layout is invalid");
+  store.vector_stride_floats = strideBytes / sizeof(float);
+  if (store.vector_stride_floats < store.dimension) throwInvalid("The vector stride is shorter than a vector");
+  Region header = heldRegion(memory.storeHeader, sizeof(int32_t), _held, "The store header");
+  if (header.elements < NARSIL_STORE_HEADER_WORDS) throwInvalid("The store header is too short");
+  store.header = reinterpret_cast<int32_t*>(header.bytes);
+  Region codePresent = heldRegion(memory.codePresent, 1, _held, "The code flags");
+  Region centroid = heldRegion(memory.centroid, sizeof(float), _held, "The centroid");
+  if (centroid.elements < store.dimension) throwInvalid("The centroid is shorter than a vector");
+  Region magnitudes = heldRegion(memory.magnitudes, sizeof(double), _held, "The magnitudes");
+  Region present = heldRegion(memory.present, 1, _held, "The presence flags");
+  Region vectorFile = heldRegion(memory.vectorFile, sizeof(int32_t), _held, "The vector file table");
+  Region vectorOffset = heldRegion(memory.vectorOffset, sizeof(uint32_t), _held, "The vector offsets");
+  store.code_present = codePresent.bytes;
+  store.centroid = reinterpret_cast<float*>(centroid.bytes);
+  store.magnitudes = reinterpret_cast<const double*>(magnitudes.bytes);
+  store.present = present.bytes;
+  store.vector_file = reinterpret_cast<const int32_t*>(vectorFile.bytes);
+  store.vector_offset = reinterpret_cast<const uint32_t*>(vectorOffset.bytes);
+  int32_t storedSlots = headerWord(store.header, NARSIL_STORE_WORD_SLOTS);
+  if (storedSlots < 0) throwInvalid("The store header is inconsistent");
+  uint64_t slots = static_cast<uint64_t>(storedSlots);
+  if (!covers(codePresent.elements, slots) || !covers(magnitudes.elements, slots) || !covers(present.elements, slots) ||
+      !covers(vectorFile.elements, slots) || !covers(vectorOffset.elements, slots)) {
+    throwInvalid("The store regions are smaller than the vectors they hold");
+  }
+  readBlocks(memory.codeBlocks, slots, store.records_per_block, narsil_record_bytes(store.dimension, store.bits), 1,
+             _held, _codeBlocks, "A code block");
+  readBlocks(memory.vectorBlocks, slots, store.vectors_per_block, strideBytes, alignof(float), _held, _vectorBlocks,
+             "A vector block");
+  store.code_blocks = _codeBlocks.data();
+  store.code_block_count = static_cast<uint32_t>(_codeBlocks.size());
+  store.vector_blocks = _vectorBlocks.data();
+  store.vector_block_count = static_cast<uint32_t>(_vectorBlocks.size());
+  _files.assign(memory.vectorFiles.size(), narsil_vector_file{nullptr, 0, nullptr});
+  for (size_t index = 0; index < memory.vectorFiles.size(); index++) {
+    const std::string& path = memory.vectorFiles[index];
+    if (path.empty()) continue;
+    if (narsil_vector_file_map(path.c_str(), &_files[index]) != NARSIL_OK) {
+      unmapFiles();
+      throwInvalid("The vector file " + path + " cannot be mapped");
+    }
+  }
+  store.files = _files.data();
+  store.file_count = static_cast<uint32_t>(_files.size());
+}
+
+HybridNarsilAttachedStoreImpl::~HybridNarsilAttachedStoreImpl() { unmapFiles(); }
+
+void HybridNarsilAttachedStoreImpl::unmapFiles() {
+  for (narsil_vector_file& file : _files) narsil_vector_file_unmap(&file);
+  _files.clear();
+  store.files = nullptr;
+  store.file_count = 0;
+}
+
+double HybridNarsilAttachedStoreImpl::detach() {
+  std::lock_guard<std::mutex> guard(_useLock);
+  _detached = true;
+  if (_backgroundUses > 0) {
+    _unmapAfterUse = true;
+    return 0;
+  }
+  unmapFiles();
+  return 0;
+}
+
+bool HybridNarsilAttachedStoreImpl::beginBackgroundUse() {
+  std::lock_guard<std::mutex> guard(_useLock);
+  if (_detached) return false;
+  _backgroundUses += 1;
+  return true;
+}
+
+void HybridNarsilAttachedStoreImpl::endBackgroundUse() {
+  std::lock_guard<std::mutex> guard(_useLock);
+  _backgroundUses -= 1;
+  if (_backgroundUses == 0 && _unmapAfterUse) {
+    _unmapAfterUse = false;
+    unmapFiles();
+  }
+}
+
+std::shared_ptr<HybridNarsilAttachedGraphImpl> attachedGraphOf(
+    const std::shared_ptr<HybridNarsilAttachedGraphSpec>& graph) {
+  auto attached = std::dynamic_pointer_cast<HybridNarsilAttachedGraphImpl>(graph);
+  if (attached == nullptr) throwInvalid("The call takes a graph that this core attached");
+  return attached;
+}
+
+std::shared_ptr<HybridNarsilAttachedStoreImpl> attachedStoreOf(
+    const std::shared_ptr<HybridNarsilAttachedStoreSpec>& store) {
+  auto attached = std::dynamic_pointer_cast<HybridNarsilAttachedStoreImpl>(store);
+  if (attached == nullptr || attached->isDetached()) throwInvalid("The call takes a store that this core attached");
+  return attached;
+}
+
+uint32_t handOverWakes(PendingWakes& wakes, const MemoryView& target) {
+  uint8_t* bytes = bytesWithin(target.buffer, target.byteOffset, target.byteLength, "The wake list");
+  size_t capacity = static_cast<size_t>(target.byteLength) / sizeof(int32_t);
+  if (bytes == nullptr || capacity < 1 || reinterpret_cast<uintptr_t>(bytes) % sizeof(int32_t) != 0) {
+    wakes.count = 0;
+    throwInvalid("The wake list must be an aligned Int32Array with room for its count");
+  }
+  auto* out = reinterpret_cast<int32_t*>(bytes);
+  uint32_t kept = wakes.count;
+  if (kept > capacity - 1) kept = static_cast<uint32_t>(capacity - 1);
+  for (uint32_t index = 0; index < kept; index++) out[index + 1] = wakes.ordinals[index];
+  out[0] = static_cast<int32_t>(kept);
+  wakes.count = 0;
+  return kept;
+}
+
+}

package/cpp/AttachedField.hpp

@@ -0,0 +1,61 @@
+#pragma once
+
+#include "GraphMemory.hpp"
+#include "HybridNarsilAttachedGraphSpec.hpp"
+#include "HybridNarsilAttachedStoreSpec.hpp"
+#include "StoreMemory.hpp"
+#include "narsil_core.h"
+
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <vector>
+
+namespace margelo::nitro::narsil {
+
+constexpr uint32_t WAKES_KEPT_PER_CALL = 256;
+
+struct PendingWakes {
+  int32_t ordinals[WAKES_KEPT_PER_CALL];
+  uint32_t count = 0;
+};
+
+class HybridNarsilAttachedGraphImpl final : public HybridNarsilAttachedGraphSpec {
+public:
+  explicit HybridNarsilAttachedGraphImpl(const GraphMemory& memory);
+  narsil_graph graph{};
+  PendingWakes wakes;
+
+private:
+  std::vector<std::shared_ptr<ArrayBuffer>> _held;
+};
+
+class HybridNarsilAttachedStoreImpl final : public HybridNarsilAttachedStoreSpec {
+public:
+  explicit HybridNarsilAttachedStoreImpl(const StoreMemory& memory);
+  ~HybridNarsilAttachedStoreImpl() override;
+  double detach() override;
+  bool isDetached() const { return _detached; }
+  bool beginBackgroundUse();
+  void endBackgroundUse();
+  narsil_store store{};
+
+private:
+  void unmapFiles();
+  std::vector<std::shared_ptr<ArrayBuffer>> _held;
+  std::vector<uint8_t*> _codeBlocks;
+  std::vector<const float*> _vectorBlocks;
+  std::vector<narsil_vector_file> _files;
+  std::mutex _useLock;
+  uint32_t _backgroundUses = 0;
+  bool _unmapAfterUse = false;
+  bool _detached = false;
+};
+
+std::shared_ptr<HybridNarsilAttachedGraphImpl> attachedGraphOf(
+    const std::shared_ptr<HybridNarsilAttachedGraphSpec>& graph);
+std::shared_ptr<HybridNarsilAttachedStoreImpl> attachedStoreOf(
+    const std::shared_ptr<HybridNarsilAttachedStoreSpec>& store);
+uint32_t handOverWakes(PendingWakes& wakes, const MemoryView& target);
+
+}

package/cpp/Compression.cpp

@@ -0,0 +1,113 @@
+#include "Compression.hpp"
+#include "HostMemory.hpp"
+
+#include <algorithm>
+#include <cerrno>
+#include <climits>
+#include <string>
+#include <vector>
+#include <zlib.h>
+
+namespace margelo::nitro::narsil {
+
+namespace {
+
+constexpr int RAW_DEFLATE_WINDOW_BITS = -15;
+constexpr int GZIP_WINDOW_BITS = 31;
+constexpr int DEFAULT_MEMORY_LEVEL = 8;
+constexpr size_t LARGEST_ZLIB_STEP = static_cast<size_t>(UINT_MAX);
+constexpr size_t FIRST_INFLATE_CAPACITY = 64 * 1024;
+
+int windowBitsOf(CompressionFormat format) {
+  return format == CompressionFormat::Gzip ? GZIP_WINDOW_BITS : RAW_DEFLATE_WINDOW_BITS;
+}
+
+uInt stepOf(size_t remaining) { return static_cast<uInt>(std::min(remaining, LARGEST_ZLIB_STEP)); }
+
+class DeflateStream {
+public:
+  explicit DeflateStream(CompressionFormat format) {
+    if (deflateInit2(&stream, Z_DEFAULT_COMPRESSION, Z_DEFLATED, windowBitsOf(format), DEFAULT_MEMORY_LEVEL,
+                     Z_DEFAULT_STRATEGY) != Z_OK) {
+      throwSystemError(ENOMEM, "start compression", "");
+    }
+  }
+  ~DeflateStream() { deflateEnd(&stream); }
+  z_stream stream{};
+};
+
+class InflateStream {
+public:
+  explicit InflateStream(CompressionFormat format) {
+    if (inflateInit2(&stream, windowBitsOf(format)) != Z_OK) throwSystemError(ENOMEM, "start decompression", "");
+  }
+  ~InflateStream() { inflateEnd(&stream); }
+  z_stream stream{};
+};
+
+}
+
+std::shared_ptr<ArrayBuffer> compressBytes(const uint8_t* source, size_t length, CompressionFormat format) {
+  DeflateStream deflater(format);
+  z_stream& stream = deflater.stream;
+  std::vector<uint8_t> output(static_cast<size_t>(deflateBound(&stream, static_cast<uLong>(length))) + 64);
+  size_t consumed = 0;
+  size_t produced = 0;
+  int status = Z_OK;
+  while (status != Z_STREAM_END) {
+    size_t remainingInput = length - consumed;
+    if (output.size() == produced) output.resize(output.size() * 2);
+    stream.next_in = const_cast<Bytef*>(source + consumed);
+    stream.avail_in = stepOf(remainingInput);
+    stream.next_out = output.data() + produced;
+    stream.avail_out = stepOf(output.size() - produced);
+    uInt offeredIn = stream.avail_in;
+    uInt offeredOut = stream.avail_out;
+    bool lastStep = offeredIn == remainingInput;
+    status = deflate(&stream, lastStep ? Z_FINISH : Z_NO_FLUSH);
+    if (status == Z_STREAM_ERROR) throwInvalid("The compressor rejected its input");
+    consumed += offeredIn - stream.avail_in;
+    produced += offeredOut - stream.avail_out;
+  }
+  output.resize(produced);
+  return ArrayBuffer::move(std::move(output));
+}
+
+std::shared_ptr<ArrayBuffer> inflateBytes(const uint8_t* source, size_t length, CompressionFormat format,
+                                          size_t maxLength) {
+  InflateStream inflater(format);
+  z_stream& stream = inflater.stream;
+  size_t capacityLimit = maxLength + 1;
+  std::vector<uint8_t> output(std::min(capacityLimit, std::max(FIRST_INFLATE_CAPACITY, length * 4)));
+  size_t consumed = 0;
+  size_t produced = 0;
+  for (;;) {
+    if (produced > maxLength) throwSystemError(EFBIG, "decompress past " + std::to_string(maxLength) + " bytes", "");
+    if (produced == output.size()) output.resize(std::min(capacityLimit, output.size() * 2));
+    stream.next_in = const_cast<Bytef*>(source + consumed);
+    stream.avail_in = stepOf(length - consumed);
+    stream.next_out = output.data() + produced;
+    stream.avail_out = stepOf(output.size() - produced);
+    uInt offeredIn = stream.avail_in;
+    uInt offeredOut = stream.avail_out;
+    int status = inflate(&stream, Z_NO_FLUSH);
+    consumed += offeredIn - stream.avail_in;
+    produced += offeredOut - stream.avail_out;
+    if (status == Z_STREAM_END) {
+      if (consumed != length) throwInvalid("The compressed data carries bytes after its end");
+      break;
+    }
+    if (status == Z_NEED_DICT || status == Z_DATA_ERROR || status == Z_STREAM_ERROR) {
+      throwInvalid("The compressed data is corrupt");
+    }
+    if (status == Z_MEM_ERROR) throwSystemError(ENOMEM, "decompress", "");
+    bool madeProgress = offeredIn != stream.avail_in || offeredOut != stream.avail_out;
+    if (consumed == length && produced < output.size()) throwInvalid("The compressed data ends early");
+    if (!madeProgress && produced < output.size()) throwInvalid("The compressed data ends early");
+  }
+  if (produced > maxLength) throwSystemError(EFBIG, "decompress past " + std::to_string(maxLength) + " bytes", "");
+  output.resize(produced);
+  return ArrayBuffer::move(std::move(output));
+}
+
+}

package/cpp/Compression.hpp

@@ -0,0 +1,16 @@
+#pragma once
+
+#include <NitroModules/ArrayBuffer.hpp>
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+
+namespace margelo::nitro::narsil {
+
+enum class CompressionFormat { RawDeflate, Gzip };
+
+std::shared_ptr<ArrayBuffer> compressBytes(const uint8_t* source, size_t length, CompressionFormat format);
+std::shared_ptr<ArrayBuffer> inflateBytes(const uint8_t* source, size_t length, CompressionFormat format,
+                                          size_t maxLength);
+
+}

package/cpp/GraphHeldAlone.cpp

@@ -0,0 +1,29 @@
+#include "GraphHeldAlone.hpp"
+#include "narsil_core.h"
+
+namespace margelo::nitro::narsil {
+
+namespace {
+
+constexpr int32_t GRAPH_LOCK_FREE = 0;
+
+}
+
+GraphHeldAlone::GraphHeldAlone(int32_t* header) : _header(header), _held(false) {
+  int32_t expected = GRAPH_LOCK_FREE;
+  _held = __atomic_compare_exchange_n(_header + NARSIL_GRAPH_WORD_LOCK, &expected, NARSIL_GRAPH_HELD_ALONE, false,
+                                      __ATOMIC_SEQ_CST, __ATOMIC_SEQ_CST);
+}
+
+GraphHeldAlone::~GraphHeldAlone() { release(); }
+
+void GraphHeldAlone::markEveryNodeLinked() {
+  if (_held && !_released.load()) __atomic_store_n(_header + NARSIL_GRAPH_WORD_UNLINKED_NODES, 0, __ATOMIC_SEQ_CST);
+}
+
+void GraphHeldAlone::release() {
+  if (!_held || _released.exchange(true)) return;
+  __atomic_store_n(_header + NARSIL_GRAPH_WORD_LOCK, GRAPH_LOCK_FREE, __ATOMIC_SEQ_CST);
+}
+
+}

package/cpp/GraphHeldAlone.hpp

@@ -0,0 +1,25 @@
+#pragma once
+
+#include <atomic>
+#include <cstdint>
+
+namespace margelo::nitro::narsil {
+
+class GraphHeldAlone {
+public:
+  explicit GraphHeldAlone(int32_t* header);
+  ~GraphHeldAlone();
+  GraphHeldAlone(const GraphHeldAlone&) = delete;
+  GraphHeldAlone& operator=(const GraphHeldAlone&) = delete;
+
+  bool held() const { return _held; }
+  void markEveryNodeLinked();
+  void release();
+
+private:
+  int32_t* _header;
+  bool _held;
+  std::atomic<bool> _released{false};
+};
+
+}

package/cpp/HostMemory.cpp

@@ -0,0 +1,123 @@
+#include "HostMemory.hpp"
+
+#include <cerrno>
+#include <cmath>
+#include <cstdlib>
+#include <cstring>
+#include <stdexcept>
+#include <sys/mman.h>
+#include <unistd.h>
+
+namespace margelo::nitro::narsil {
+
+namespace {
+
+constexpr double LARGEST_EXACT_BYTE_COUNT = 9007199254740991.0;
+
+const char* errorName(int number) {
+  switch (number) {
+    case ENOENT: return "ENOENT";
+    case EEXIST: return "EEXIST";
+    case EISDIR: return "EISDIR";
+    case ENOTDIR: return "ENOTDIR";
+    case EACCES: return "EACCES";
+    case EPERM: return "EPERM";
+    case EINVAL: return "EINVAL";
+    case ENOTSUP: return "ENOTSUP";
+    case ENOSPC: return "ENOSPC";
+    case EIO: return "EIO";
+    case EBADF: return "EBADF";
+    case ENOTEMPTY: return "ENOTEMPTY";
+    case EXDEV: return "EXDEV";
+    case EMFILE: return "EMFILE";
+    case ENFILE: return "ENFILE";
+    case EROFS: return "EROFS";
+    case EBUSY: return "EBUSY";
+    case ENAMETOOLONG: return "ENAMETOOLONG";
+    case ELOOP: return "ELOOP";
+    case EAGAIN: return "EAGAIN";
+    case EFBIG: return "EFBIG";
+    case EDQUOT: return "EDQUOT";
+    case ENOMEM: return "ENOMEM";
+    case ESRCH: return "ESRCH";
+    default: return "EUNKNOWN";
+  }
+}
+
+size_t pageBytes() {
+  long page = sysconf(_SC_PAGESIZE);
+  return page > 0 ? static_cast<size_t>(page) : 4096;
+}
+
+}
+
+ReservedRegion::ReservedRegion(uint8_t* data, size_t size, size_t mappedSize)
+    : _data(data), _size(size), _mappedSize(mappedSize) {}
+
+ReservedRegion::~ReservedRegion() { munmap(_data, _mappedSize); }
+
+AllocatedBuffer::AllocatedBuffer(uint8_t* data, size_t size) : _data(data), _size(size) {}
+
+AllocatedBuffer::~AllocatedBuffer() { std::free(_data); }
+
+void throwSystemError(int number, const std::string& operation, const std::string& subject) {
+  std::string message = std::string("[") + errorName(number) + "] " + operation;
+  if (!subject.empty()) message += " '" + subject + "'";
+  message += ": ";
+  message += std::strerror(number);
+  throw std::runtime_error(message);
+}
+
+void throwInvalid(const std::string& message) { throw std::invalid_argument("[EINVAL] " + message); }
+
+size_t requireByteCount(double value, const char* what) {
+  if (!std::isfinite(value) || value < 0 || value > LARGEST_EXACT_BYTE_COUNT || std::floor(value) != value) {
+    throwInvalid(std::string(what) + " must be a whole number of bytes from 0 up");
+  }
+  return static_cast<size_t>(value);
+}
+
+uint8_t* bytesWithin(const std::shared_ptr<ArrayBuffer>& buffer, double byteOffset, double byteLength,
+                     const char* what) {
+  if (buffer == nullptr) throwInvalid(std::string(what) + " has no buffer");
+  size_t offset = requireByteCount(byteOffset, what);
+  size_t length = requireByteCount(byteLength, what);
+  size_t held = buffer->size();
+  if (offset > held || length > held - offset) {
+    throwInvalid(std::string(what) + " reaches past the end of its buffer");
+  }
+  uint8_t* base = buffer->data();
+  if (base == nullptr) {
+    if (length == 0) return nullptr;
+    throwInvalid(std::string(what) + " has a detached buffer");
+  }
+  return base + offset;
+}
+
+std::shared_ptr<ArrayBuffer> reserveRegion(double bytes) {
+  size_t size = requireByteCount(bytes, "A reservation");
+  if (size == 0) throwInvalid("A reservation needs at least one byte");
+  size_t page = pageBytes();
+  if (size > SIZE_MAX - page) throwSystemError(ENOMEM, "reserve memory", std::to_string(size) + " bytes");
+  size_t mapped = (size + page - 1) / page * page;
+  int flags = MAP_PRIVATE | MAP_ANON;
+#ifdef MAP_NORESERVE
+  flags |= MAP_NORESERVE;
+#endif
+  void* address = mmap(nullptr, mapped, PROT_READ | PROT_WRITE, flags, -1, 0);
+  if (address == MAP_FAILED) throwSystemError(errno, "reserve memory", std::to_string(size) + " bytes");
+  return std::make_shared<ReservedRegion>(static_cast<uint8_t*>(address), size, mapped);
+}
+
+std::shared_ptr<ArrayBuffer> allocateZeroed(double bytes) {
+  size_t size = requireByteCount(bytes, "An allocation");
+  void* data = std::calloc(size == 0 ? 1 : size, 1);
+  if (data == nullptr) throwSystemError(ENOMEM, "allocate memory", std::to_string(size) + " bytes");
+  return std::make_shared<AllocatedBuffer>(static_cast<uint8_t*>(data), size);
+}
+
+bool isHostOwned(const std::shared_ptr<ArrayBuffer>& buffer) {
+  return std::dynamic_pointer_cast<HostOwnedBuffer>(buffer) != nullptr;
+}
+
+}

package/cpp/HostMemory.hpp

@@ -0,0 +1,53 @@
+#pragma once
+
+#include <NitroModules/ArrayBuffer.hpp>
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <string>
+
+namespace margelo::nitro::narsil {
+
+class HostOwnedBuffer : public ArrayBuffer {
+public:
+  bool isOwner() const noexcept override { return true; }
+  size_t getExternalMemorySize() const override { return 0; }
+};
+
+class ReservedRegion final : public HostOwnedBuffer {
+public:
+  ReservedRegion(uint8_t* data, size_t size, size_t mappedSize);
+  ~ReservedRegion() override;
+  uint8_t* data() override { return _data; }
+  size_t size() const override { return _size; }
+
+private:
+  uint8_t* _data;
+  size_t _size;
+  size_t _mappedSize;
+};
+
+class AllocatedBuffer final : public HostOwnedBuffer {
+public:
+  AllocatedBuffer(uint8_t* data, size_t size);
+  ~AllocatedBuffer() override;
+  uint8_t* data() override { return _data; }
+  size_t size() const override { return _size; }
+
+private:
+  uint8_t* _data;
+  size_t _size;
+};
+
+std::shared_ptr<ArrayBuffer> reserveRegion(double bytes);
+std::shared_ptr<ArrayBuffer> allocateZeroed(double bytes);
+bool isHostOwned(const std::shared_ptr<ArrayBuffer>& buffer);
+
+size_t requireByteCount(double value, const char* what);
+uint8_t* bytesWithin(const std::shared_ptr<ArrayBuffer>& buffer, double byteOffset, double byteLength,
+                     const char* what);
+
+[[noreturn]] void throwSystemError(int number, const std::string& operation, const std::string& subject);
+[[noreturn]] void throwInvalid(const std::string& message);
+
+}