Skip to content

Run frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦

C

feat(st): add read-only tensor mapping primitive

bheraldfc8020e4d14a
diff --git a/c/Makefile b/c/Makefile
index d978bc49..a24cd227 100644
--- a/c/Makefile
+++ b/c/Makefile
@@ -768,6 +768,9 @@ tests/test_tok_kimi_tiny$(EXE): tests/test_tok_kimi_tiny.c tok.h tok_unicode.h t
tests/test_st_pread$(EXE): tests/test_st_pread.c st.h json.h compat.h
$(CC) $(CFLAGS) -DST_PREAD_CHUNK=7 $< -o $@ $(LDFLAGS)
+tests/test_st_map$(EXE): tests/test_st_map.c st.h json.h compat.h
+ $(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
+
tests/test_st_shape$(EXE): tests/test_st_shape.c st.h json.h compat.h
$(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)
diff --git a/c/compat.h b/c/compat.h
index 712371f4..21407cc5 100644
--- a/c/compat.h
+++ b/c/compat.h
@@ -11,6 +11,15 @@
#ifndef COMPAT_H
#define COMPAT_H
+#include <errno.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+#ifndef _WIN32
+#include <sys/mman.h>
+#include <unistd.h>
+#endif
+
#ifdef __APPLE__
#include <fcntl.h>
#include <unistd.h>
@@ -386,6 +395,77 @@ static inline char *compat_mkdtemp(char *tmpl){
#define COMPAT_O_BINARY 0
#endif
+/* --- read-only file mapping -------------------------------------------------
+ * A small ownership-carrying primitive for safetensors that are already in the
+ * engine's final byte representation. The caller gets a pointer to the exact
+ * requested (possibly unaligned) range while this object retains the aligned
+ * OS view needed to release it safely.
+ *
+ * This does not prefetch or lock pages. Mapping changes ownership/accounting,
+ * not the model's active working set: pages are faulted when the caller reads
+ * them and remain reclaimable file-backed cache pages. */
+typedef struct {
+ void *base;
+ size_t len;
+#ifdef _WIN32
+ HANDLE mapping;
+#endif
+} compat_ro_map;
+
+static inline int compat_map_readonly(int fd, int64_t off, size_t len,
+ compat_ro_map *map, const void **data)
+{
+ if (!map || !data || off < 0 || len == 0) { errno = EINVAL; return -1; }
+ memset(map, 0, sizeof(*map));
+#ifdef _WIN32
+ intptr_t osfh = _get_osfhandle(fd);
+ if (osfh == -1 || osfh == -2) { errno = EBADF; return -1; }
+ SYSTEM_INFO si;
+ GetSystemInfo(&si);
+ uint64_t gran = si.dwAllocationGranularity ? si.dwAllocationGranularity : 65536u;
+ uint64_t aligned = (uint64_t)off - ((uint64_t)off % gran);
+ uint64_t delta = (uint64_t)off - aligned;
+ if (delta > SIZE_MAX || len > SIZE_MAX - (size_t)delta) { errno = EOVERFLOW; return -1; }
+ size_t view_len = (size_t)delta + len;
+ HANDLE fm = CreateFileMappingA((HANDLE)osfh, NULL, PAGE_READONLY, 0, 0, NULL);
+ if (!fm) { errno = EIO; return -1; }
+ void *base = MapViewOfFile(fm, FILE_MAP_READ,
+ (DWORD)(aligned >> 32), (DWORD)(aligned & 0xffffffffu),
+ view_len);
+ if (!base) { CloseHandle(fm); errno = EIO; return -1; }
+ map->base = base;
+ map->len = view_len;
+ map->mapping = fm;
+ *data = (const char*)base + (size_t)delta;
+#else
+ long pg = sysconf(_SC_PAGESIZE);
+ if (pg <= 0) pg = 4096;
+ uint64_t gran = (uint64_t)pg;
+ uint64_t aligned = (uint64_t)off - ((uint64_t)off % gran);
+ uint64_t delta = (uint64_t)off - aligned;
+ if (delta > SIZE_MAX || len > SIZE_MAX - (size_t)delta) { errno = EOVERFLOW; return -1; }
+ size_t view_len = (size_t)delta + len;
+ void *base = mmap(NULL, view_len, PROT_READ, MAP_SHARED, fd, (off_t)aligned);
+ if (base == MAP_FAILED) return -1;
+ map->base = base;
+ map->len = view_len;
+ *data = (const char*)base + (size_t)delta;
+#endif
+ return 0;
+}
+
+static inline void compat_unmap_readonly(compat_ro_map *map)
+{
+ if (!map || !map->base) return;
+#ifdef _WIN32
+ UnmapViewOfFile(map->base);
+ if (map->mapping) CloseHandle(map->mapping);
+#else
+ munmap(map->base, map->len);
+#endif
+ memset(map, 0, sizeof(*map));
+}
+
/* --- coli_stdin_readable: "c'e' input su stdin adesso?", senza bloccare ---
*
* I serve loop di inkling.c e kimi_k3.c usavano select() su fd_set direttamente.
diff --git a/c/st.h b/c/st.h
index 7261adf4..41d5e0b1 100644
--- a/c/st.h
+++ b/c/st.h
@@ -825,6 +825,36 @@ static void st_read_raw_cap(shards *S, const char *name, void *out, int64_t cap,
st_read_raw(S, name, out, drop);
}
+/* Read-only view of one tensor's exact stored bytes. Unlike st_read_raw this
+ * performs no allocation or copy; unlike a naked mmap pointer it carries the
+ * aligned OS view/handle required for cleanup. Callers must still validate
+ * dtype and shape for their own format before consuming `data`. */
+typedef struct {
+ compat_ro_map map;
+ const void *data;
+ int64_t nbytes;
+} st_mapped_raw;
+
+static int st_map_raw(shards *S, const char *name, st_mapped_raw *out) {
+ st_tensor *t = st_find(S, name);
+ if (!t) { fprintf(stderr, "missing tensor: %s\n", name); return -1; }
+ if (!out || t->nbytes <= 0 || (uint64_t)t->nbytes > SIZE_MAX) {
+ errno = EINVAL; return -1;
+ }
+ memset(out, 0, sizeof(*out));
+ if (compat_map_readonly(t->fd, t->off, (size_t)t->nbytes,
+ &out->map, &out->data) != 0) return -1;
+ out->nbytes = t->nbytes;
+ return 0;
+}
+
+static void st_unmap_raw(st_mapped_raw *mapped) {
+ if (!mapped) return;
+ compat_unmap_readonly(&mapped->map);
+ mapped->data = NULL;
+ mapped->nbytes = 0;
+}
+
/* legge una FETTA di un tensore: n_elems a partire dall'elemento elem_off.
* Serve per gli expert fusi di GLM (un tensore = blocco [E, ...]): si legge il
* solo expert richiesto via pread del sotto-range, niente lettura dell'intero blocco. */
diff --git a/c/tests/test_st_map.c b/c/tests/test_st_map.c
new file mode 100644
index 00000000..2364989d
--- /dev/null
+++ b/c/tests/test_st_map.c
@@ -0,0 +1,70 @@
+#define _GNU_SOURCE
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "../st.h"
+
+#define CHECK(condition) do { \
+ if (!(condition)) { \
+ fprintf(stderr, "%s:%d: check failed: %s\n", __FILE__, __LINE__, #condition); \
+ return 1; \
+ } \
+} while (0)
+
+static void write_snap(const char *dir) {
+ char path[512];
+ snprintf(path, sizeof(path), "%s/model.safetensors", dir);
+ const char *hdr =
+ "{\"weight\":{\"dtype\":\"U8\",\"shape\":[17],\"data_offsets\":[0,17]},"
+ "\"weight.qs\":{\"dtype\":\"F32\",\"shape\":[2],\"data_offsets\":[17,25]}}";
+ uint64_t hlen = strlen(hdr);
+ unsigned char weight[17];
+ float scales[2] = {0.25f, 1.5f};
+ for (int i = 0; i < 17; i++) weight[i] = (unsigned char)(i * 11 + 5);
+ FILE *f = fopen(path, "wb");
+ fwrite(&hlen, 8, 1, f);
+ fwrite(hdr, 1, hlen, f);
+ fwrite(weight, 1, sizeof(weight), f);
+ fwrite(scales, 1, sizeof(scales), f);
+ fclose(f);
+}
+
+int main(void) {
+ char dir[] = "test_st_map_XXXXXX";
+ CHECK(mkdtemp(dir) != NULL);
+ write_snap(dir);
+
+ shards S;
+ st_init(&S, dir);
+
+ st_mapped_raw weight = {0}, scales = {0};
+ CHECK(st_map_raw(&S, "weight", &weight) == 0);
+ CHECK(weight.nbytes == 17);
+ const unsigned char *w = (const unsigned char*)weight.data;
+ for (int i = 0; i < 17; i++) CHECK(w[i] == (unsigned char)(i * 11 + 5));
+
+ /* The second tensor begins at an unaligned file offset. The mapping
+ * primitive must align the OS view while returning the exact tensor byte. */
+ CHECK(st_map_raw(&S, "weight.qs", &scales) == 0);
+ CHECK(scales.nbytes == 8);
+ float s[2];
+ memcpy(s, scales.data, sizeof(s));
+ CHECK(s[0] == 0.25f && s[1] == 1.5f);
+
+ st_unmap_raw(&scales);
+ st_unmap_raw(&weight);
+ CHECK(scales.data == NULL && scales.nbytes == 0);
+ CHECK(weight.data == NULL && weight.nbytes == 0);
+
+ char cmd[600];
+#ifdef _WIN32
+ snprintf(cmd, sizeof(cmd), "rmdir /s /q %s", dir);
+#else
+ snprintf(cmd, sizeof(cmd), "rm -rf %s", dir);
+#endif
+ if (system(cmd)) {}
+ printf("test_st_map: exact unaligned read-only tensor views: ok\n");
+ return 0;
+}