From c4158acac9f45321c38a2222b30b546ed0598737 Mon Sep 17 00:00:00 2001
From: guangli-dai <gdai@meta.com>
Date: Sun, 26 Jul 2026 17:04:13 -0700
Subject: [PATCH] OS layer scaffolding (dispatcher)

Introduce the `os.h` dispatcher pattern under
`include/jemalloc/internal/os/`, with no modules wired in yet.

  - os.h        - documents the os/<module>.h dispatcher / os/posix/
                  default / os/<os>/ override pattern that every
                  facility will follow.
  - os/detect.h - JEMALLOC_OS_POSIX platform detection, shared by every
                  module dispatcher.
---
 .gitignore                            |  2 ++
 include/jemalloc/internal/os.h        | 26 ++++++++++++++++++++++++++
 include/jemalloc/internal/os/detect.h | 26 ++++++++++++++++++++++++++
 3 files changed, 54 insertions(+)
 create mode 100644 include/jemalloc/internal/os.h
 create mode 100644 include/jemalloc/internal/os/detect.h

diff --git a/.gitignore b/.gitignore
index 95dbaa5f..1296a4a6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,6 +44,8 @@
 
 /src/*.[od]
 /src/*.sym
+/src/os/*.[od]
+/src/os/*.sym
 
 # These are semantically meaningful for clangd and related tooling.
 /build/
diff --git a/include/jemalloc/internal/os.h b/include/jemalloc/internal/os.h
new file mode 100644
index 00000000..1bf8afb7
--- /dev/null
+++ b/include/jemalloc/internal/os.h
@@ -0,0 +1,26 @@
+#ifndef JEMALLOC_INTERNAL_OS_H
+#define JEMALLOC_INTERNAL_OS_H
+
+/*
+ * OS layer.
+ *
+ * Portable code includes this header to reach the OS-touching primitives it
+ * needs.  Each facility is a module with its own dispatcher (os/<module>.h)
+ * that selects an implementation:
+ *
+ *   os/posix/<module>.h  - the default, used by every POSIX platform.
+ *   os/<os>/<module>.h   - an override, present ONLY when an OS specializes
+ *                          that module.
+ *
+ * A dispatcher picks the OS-specific file when one exists and otherwise falls
+ * back to posix/ (guarded by JEMALLOC_OS_POSIX), so any POSIX platform builds
+ * without being enumerated anywhere.  A non-POSIX platform with no override
+ * hits a #error.
+ *
+ * Adding OS support for a module (only when existing module headers cannot be
+ * reused): create os/<os>/<module>.h (and later a matching src body when
+ * necessary and add one branch to os/<module>.h.  Adding a whole new module:
+ * module: create os/<module>.h + os/posix/<module>.h and #include it below.
+ */
+
+#endif /* JEMALLOC_INTERNAL_OS_H */
diff --git a/include/jemalloc/internal/os/detect.h b/include/jemalloc/internal/os/detect.h
new file mode 100644
index 00000000..b08eb4e7
--- /dev/null
+++ b/include/jemalloc/internal/os/detect.h
@@ -0,0 +1,26 @@
+#ifndef JEMALLOC_INTERNAL_OS_DETECT_H
+#define JEMALLOC_INTERNAL_OS_DETECT_H
+
+/*
+ * Platform detection for the OS-layer dispatchers.
+ *
+ * Defines JEMALLOC_OS_POSIX when the target is POSIX, so a module dispatcher
+ * can fall back to os/posix/<module>.h for ANY POSIX platform without that
+ * platform being enumerated.  We treat the target as POSIX if the C library
+ * advertises _POSIX_VERSION (via <unistd.h>) or the compiler predefines
+ * __unix__/__unix.  Windows is handled by its own _WIN32 branch and never
+ * reaches here.
+ *
+ * Included (idempotently) by os.h and by every module dispatcher, so the
+ * dispatchers work whether reached through os.h or directly.
+ */
+#if !defined(_WIN32)
+#  if !defined(__has_include) || __has_include(<unistd.h>)
+#    include <unistd.h>
+#  endif
+#  if defined(_POSIX_VERSION) || defined(__unix__) || defined(__unix)
+#    define JEMALLOC_OS_POSIX
+#  endif
+#endif
+
+#endif /* JEMALLOC_INTERNAL_OS_DETECT_H */