@camstack/shm-ring 0.1.2

package/src/shm.cc

@@ -0,0 +1,321 @@
+/*
+ * shm_ring — CamStack shared-memory segment N-API addon.
+ *
+ * Maps/unmaps a named OS shared-memory segment and hands JS a zero-copy
+ * Buffer over the mapping. No ring/seqlock logic here (that is pure TS,
+ * Task 2). One #ifdef _WIN32 split:
+ *   - POSIX (macOS/Linux): shm_open + ftruncate + mmap / munmap / shm_unlink.
+ *   - Windows: CreateFileMappingW / OpenFileMappingW + MapViewOfFile,
+ *     UnmapViewOfFile + CloseHandle; the OS reclaims the segment when the
+ *     last handle closes, so unlink() is a documented no-op.
+ *
+ * Each create()/open() returns { buffer, handle } where `handle` is an
+ * Napi::External wrapping a heap-allocated ShmHandle. close(handle) reaches
+ * the native ShmHandle to unmap. The Buffer finalizer does NOT free the
+ * mapping — close() owns that lifecycle.
+ */
+#include <napi.h>
+
+#include <cstdint>
+#include <string>
+
+#ifdef _WIN32
+#include <windows.h>
+#else
+#include <fcntl.h>
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <unistd.h>
+#include <cerrno>
+#include <cstring>
+#endif
+
+namespace {
+
+// Native-side record for a single mapped segment. Heap-allocated; its
+// lifetime is owned by the JS-side Napi::External handle.
+struct ShmHandle {
+  void* ptr = nullptr;
+  size_t byteLength = 0;
+#ifdef _WIN32
+  HANDLE mapping = nullptr;
+#else
+  int fd = -1;
+#endif
+  bool unmapped = false;
+};
+
+#ifdef _WIN32
+
+// Translate a UTF-8 segment name into a wide string for the Win32 W APIs.
+std::wstring Widen(const std::string& utf8) {
+  if (utf8.empty()) return std::wstring();
+  int len = MultiByteToWideChar(CP_UTF8, 0, utf8.c_str(),
+                                static_cast<int>(utf8.size()), nullptr, 0);
+  std::wstring wide(static_cast<size_t>(len), L'\0');
+  MultiByteToWideChar(CP_UTF8, 0, utf8.c_str(),
+                      static_cast<int>(utf8.size()), &wide[0], len);
+  return wide;
+}
+
+#endif
+
+// Unmap a segment's view of the mapping. Idempotent.
+void UnmapHandle(ShmHandle* handle) {
+  if (handle == nullptr || handle->unmapped) return;
+  handle->unmapped = true;
+#ifdef _WIN32
+  if (handle->ptr != nullptr) {
+    UnmapViewOfFile(handle->ptr);
+  }
+  if (handle->mapping != nullptr) {
+    CloseHandle(handle->mapping);
+    handle->mapping = nullptr;
+  }
+#else
+  if (handle->ptr != nullptr && handle->ptr != MAP_FAILED) {
+    munmap(handle->ptr, handle->byteLength);
+  }
+  if (handle->fd >= 0) {
+    ::close(handle->fd);
+    handle->fd = -1;
+  }
+#endif
+  handle->ptr = nullptr;
+}
+
+// Finalizer for the Napi::External wrapping a ShmHandle. If JS dropped the
+// handle without an explicit close(), unmap here as a safety net, then free.
+void FinalizeHandle(Napi::Env /*env*/, ShmHandle* handle) {
+  if (handle == nullptr) return;
+  UnmapHandle(handle);
+  delete handle;
+}
+
+// Build the { buffer, handle } result object. The Buffer finalizer is a
+// no-op — close()/the External finalizer own the unmap.
+Napi::Object MakeSegment(Napi::Env env, ShmHandle* handle) {
+  Napi::Buffer<uint8_t> buffer = Napi::Buffer<uint8_t>::New(
+      env, static_cast<uint8_t*>(handle->ptr), handle->byteLength,
+      [](Napi::Env, uint8_t*) { /* mapping freed by close()/External */ });
+
+  Napi::External<ShmHandle> external =
+      Napi::External<ShmHandle>::New(env, handle, FinalizeHandle);
+
+  Napi::Object result = Napi::Object::New(env);
+  result.Set("buffer", buffer);
+  result.Set("handle", external);
+  return result;
+}
+
+// create(name: string, byteLength: number) -> { buffer, handle }
+Napi::Value Create(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 2 || !info[0].IsString() || !info[1].IsNumber()) {
+    Napi::TypeError::New(env, "create(name: string, byteLength: number)")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  std::string name = info[0].As<Napi::String>().Utf8Value();
+  int64_t requested = info[1].As<Napi::Number>().Int64Value();
+  if (requested <= 0) {
+    Napi::RangeError::New(env, "byteLength must be > 0")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  size_t byteLength = static_cast<size_t>(requested);
+
+#ifdef _WIN32
+  std::wstring wname = Widen(name);
+  DWORD hi = static_cast<DWORD>((static_cast<uint64_t>(byteLength) >> 32) & 0xffffffff);
+  DWORD lo = static_cast<DWORD>(static_cast<uint64_t>(byteLength) & 0xffffffff);
+  HANDLE mapping = CreateFileMappingW(INVALID_HANDLE_VALUE, nullptr,
+                                      PAGE_READWRITE, hi, lo, wname.c_str());
+  if (mapping == nullptr) {
+    std::string msg = "CreateFileMappingW failed: GetLastError=";
+    msg += std::to_string(GetLastError());
+    Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  if (GetLastError() == ERROR_ALREADY_EXISTS) {
+    CloseHandle(mapping);
+    Napi::Error::New(env, "shared-memory segment already exists")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  void* ptr = MapViewOfFile(mapping, FILE_MAP_ALL_ACCESS, 0, 0, byteLength);
+  if (ptr == nullptr) {
+    std::string msg = "MapViewOfFile failed: GetLastError=";
+    msg += std::to_string(GetLastError());
+    CloseHandle(mapping);
+    Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  ShmHandle* handle = new ShmHandle();
+  handle->ptr = ptr;
+  handle->byteLength = byteLength;
+  handle->mapping = mapping;
+#else
+  int fd = shm_open(name.c_str(), O_CREAT | O_EXCL | O_RDWR, 0600);
+  if (fd < 0) {
+    std::string msg = "shm_open(create) failed: ";
+    msg += std::strerror(errno);
+    Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  if (ftruncate(fd, static_cast<off_t>(byteLength)) != 0) {
+    std::string msg = "ftruncate failed: ";
+    msg += std::strerror(errno);
+    ::close(fd);
+    shm_unlink(name.c_str());
+    Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  void* ptr = mmap(nullptr, byteLength, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
+  if (ptr == MAP_FAILED) {
+    std::string msg = "mmap failed: ";
+    msg += std::strerror(errno);
+    ::close(fd);
+    shm_unlink(name.c_str());
+    Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  ShmHandle* handle = new ShmHandle();
+  handle->ptr = ptr;
+  handle->byteLength = byteLength;
+  handle->fd = fd;
+#endif
+
+  return MakeSegment(env, handle);
+}
+
+// open(name: string, byteLength: number) -> { buffer, handle }
+Napi::Value Open(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 2 || !info[0].IsString() || !info[1].IsNumber()) {
+    Napi::TypeError::New(env, "open(name: string, byteLength: number)")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  std::string name = info[0].As<Napi::String>().Utf8Value();
+  int64_t requested = info[1].As<Napi::Number>().Int64Value();
+  if (requested <= 0) {
+    Napi::RangeError::New(env, "byteLength must be > 0")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  size_t byteLength = static_cast<size_t>(requested);
+
+#ifdef _WIN32
+  std::wstring wname = Widen(name);
+  HANDLE mapping = OpenFileMappingW(FILE_MAP_ALL_ACCESS, FALSE, wname.c_str());
+  if (mapping == nullptr) {
+    std::string msg = "OpenFileMappingW failed: segment not found: GetLastError=";
+    msg += std::to_string(GetLastError());
+    Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  // MapViewOfFile rejects a view larger than the segment with
+  // ERROR_ACCESS_DENIED — it fails cleanly, no SIGBUS risk like POSIX.
+  void* ptr = MapViewOfFile(mapping, FILE_MAP_ALL_ACCESS, 0, 0, byteLength);
+  if (ptr == nullptr) {
+    std::string msg = "MapViewOfFile failed: GetLastError=";
+    msg += std::to_string(GetLastError());
+    CloseHandle(mapping);
+    Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  ShmHandle* handle = new ShmHandle();
+  handle->ptr = ptr;
+  handle->byteLength = byteLength;
+  handle->mapping = mapping;
+#else
+  int fd = shm_open(name.c_str(), O_RDWR, 0600);
+  if (fd < 0) {
+    std::string msg = "shm_open(open) failed: ";
+    msg += std::strerror(errno);
+    Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  // mmap() with a length past the real segment size succeeds; later
+  // access past st_size faults with an uncatchable SIGBUS. Reject an
+  // oversized request up front against the segment's actual size.
+  struct stat st;
+  if (fstat(fd, &st) != 0) {
+    std::string msg = "fstat failed: ";
+    msg += std::strerror(errno);
+    ::close(fd);
+    Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  if (static_cast<uint64_t>(byteLength) >
+      static_cast<uint64_t>(st.st_size)) {
+    std::string msg = "open: requested byteLength ";
+    msg += std::to_string(static_cast<uint64_t>(byteLength));
+    msg += " exceeds segment size ";
+    msg += std::to_string(static_cast<uint64_t>(st.st_size));
+    ::close(fd);
+    Napi::RangeError::New(env, msg).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  void* ptr = mmap(nullptr, byteLength, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
+  if (ptr == MAP_FAILED) {
+    std::string msg = "mmap failed: ";
+    msg += std::strerror(errno);
+    ::close(fd);
+    Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  ShmHandle* handle = new ShmHandle();
+  handle->ptr = ptr;
+  handle->byteLength = byteLength;
+  handle->fd = fd;
+#endif
+
+  return MakeSegment(env, handle);
+}
+
+// close(handle: External<ShmHandle>) -> void. Unmaps this process's view.
+Napi::Value Close(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsExternal()) {
+    Napi::TypeError::New(env, "close(handle) expects a segment handle")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  ShmHandle* handle = info[0].As<Napi::External<ShmHandle>>().Data();
+  UnmapHandle(handle);
+  return env.Undefined();
+}
+
+// unlink(name: string) -> void. POSIX: shm_unlink. Windows: no-op (the OS
+// reclaims the segment once the last mapping handle is closed).
+Napi::Value Unlink(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsString()) {
+    Napi::TypeError::New(env, "unlink(name: string)")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+#ifndef _WIN32
+  std::string name = info[0].As<Napi::String>().Utf8Value();
+  if (shm_unlink(name.c_str()) != 0) {
+    std::string msg = "shm_unlink failed: ";
+    msg += std::strerror(errno);
+    Napi::Error::New(env, msg).ThrowAsJavaScriptException();
+  }
+#endif
+  return env.Undefined();
+}
+
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+  exports.Set("create", Napi::Function::New(env, Create));
+  exports.Set("open", Napi::Function::New(env, Open));
+  exports.Set("close", Napi::Function::New(env, Close));
+  exports.Set("unlink", Napi::Function::New(env, Unlink));
+  return exports;
+}
+
+}  // namespace
+
+NODE_API_MODULE(shm_ring, Init)