libmempressure 0.1.0__tar.gz

libmempressure-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kutu OS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

libmempressure-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+include src/mempressure.c
+include include/mempressure.h
+include bindings/python/mempressure_module.c

libmempressure-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: libmempressure
+Version: 0.1.0
+Summary: Memory-pressure events from kernel PSI: an onTrimMemory for Linux (Python binding)
+Author: kutu OS contributors
+License-Expression: MIT
+Project-URL: Homepage, https://kutu.so
+Project-URL: Repository, https://github.com/kutuso/libmempressure
+Project-URL: Documentation, https://kutu.so/#/LIBMEMPRESSURE.md
+Keywords: memory,psi,pressure,linux,oom,swap,performance
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Operating System Kernels :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# libmempressure — a Linux answer to Android's onTrimMemory
+
+Apps on Android never get OOM-killed without warning: the OS sends them
+`onTrimMemory()` callbacks and they shed caches gracefully. Desktop Linux
+just kills them. `libmempressure` closes that gap: it watches the kernel's
+[Pressure Stall Information](https://docs.kernel.org/admin-guide/perf/psi.html)
+and delivers memory-pressure events to your application — in **C, C++, Java
+(JVM) and Python** — so instead of dying under pressure, your app trims.
+
+```
+level       some avg10   what your app should do
+----------- ------------ ------------------------------------
+none        < 5%         business as usual
+low         >= 5%        stop prefetching, trim opportunistically
+moderate    >= 15%       drop object caches, shrink pools
+critical    >= 40%       shed everything, survive
+```
+
+Events are level *changes* only, filtered by hysteresis (consecutive
+readings) so your callback doesn't flap. The monitor reads
+`/proc/pressure/memory` on its own thread; callbacks fire from that thread.
+
+## The C API
+
+```c
+#include <mempressure.h>
+
+static void on_pressure(mp_level_t level, void *userdata) {
+    if (level >= MP_LEVEL_MODERATE) cache_drop_all();
+}
+
+mp_init(NULL);                       /* defaults; zero fields fall back too */
+mp_subscribe(on_pressure, my_app);
+/* ... */
+mp_shutdown();
+```
+
+`mp_config_t` tunes thresholds (5/15/40%), poll interval (0.5s) and
+hysteresis (2 readings); any zero field falls back to its default. See
+[`include/mempressure.h`](include/mempressure.h) for the full contract —
+threading rules, error codes, and the `psi_path` override (used by the test
+suites to drive the monitor from fixture files).
+
+## C++
+
+Header-only RAII wrapper — [`bindings/c++/mempressure.hpp`](bindings/c++/mempressure.hpp):
+
+```cpp
+mp::Monitor monitor;                 /* starts the monitor */
+monitor.subscribe([](mp::Level level) {
+    if (level >= mp::Level::Moderate) cache_drop_all();
+});                                  /* std::function, refcounted lifetime */
+```
+
+## JVM (JNI)
+
+```java
+import io.kutu.mempressure.MemPressure;
+
+MemPressure.start(new MemPressure.Config());
+int handle = MemPressure.subscribe(level -> {
+    if (level >= 2) cache.dropAll();          // 0=none 1=low 2=moderate 3=critical
+});
+MemPressure.unsubscribe(handle);
+MemPressure.stop();
+```
+
+Native side: `bindings/jvm/jni/mempressure_jni.c` (`libmempressure_jni.so`),
+built automatically when a JDK is present. Callbacks arrive on a daemon
+thread attached to the JVM.
+
+## Python
+
+```python
+import mempressure as mp
+
+mp.start()                                    # defaults
+mp.subscribe(lambda level: level >= 2 and cache.drop_all())
+print(mp.psi())                               # {'some_avg10': 0.12, ...}
+mp.stop()
+```
+
+CPython extension (`mempressure` module) built against your interpreter;
+callbacks fire with the GIL acquired from the monitor thread.
+
+## Build and test
+
+```sh
+make test          # cmake build + ctest (C core, C++ binding, JVM binding)
+                   # + python binding tests (needs a venv with pytest, see below)
+```
+
+Details:
+
+```sh
+cmake -S . -B build                # auto-detects Python dev + JDK; skips gracefully
+cmake --build build
+ctest --test-dir build --output-on-failure
+python3 -m venv .venv && .venv/bin/pip install pytest
+.venv/bin/pytest tests/python -q   # (build with -DPython3_EXECUTABLE=.venv/bin/python
+                                   #  if your system python differs from the venv's)
+```
+
+The test suites never require real memory pressure: they point the monitor at
+fixture files via `psi_path` and mutate them to drive level changes. The
+example binary (`mp_example_c`) runs against your real
+`/proc/pressure/memory`.
+
+## Distro packaging (RPM / DEB)
+
+The library is plain C11 + pthreads and installs via CMake's GNUInstallDirs,
+so it lands correctly on any FHS distro (including `/usr/lib64` RPM
+convention). Upstream ships packaging metadata:
+
+- **RPM** (Fedora/RHEL/openSUSE): [`packaging/rpm/libmempressure.spec`](packaging/rpm/libmempressure.spec).
+  Build a tarball and rpmbuild it, or point a COPR at the spec:
+
+  ```sh
+  git archive --prefix=libmempressure-0.1.0/ -o libmempressure-0.1.0.tar.gz HEAD
+  rpmbuild -bb packaging/rpm/libmempressure.spec --define "_sourcedir $PWD"
+  ```
+
+- **DEB** (Debian/Ubuntu): a `debian/` directory with `libmempressure0`
+  (runtime) and `libmempressure-dev` packages, native-format source:
+
+  ```sh
+  sudo apt install build-essential cmake debhelper pkg-config
+  dpkg-buildpackage -us -uc -b
+  ```
+
+Distro packages ship the C core and the header-only C++ binding
+(`-DMP_PYTHON=OFF -DMP_JAVA=OFF` in the build); the Python and JVM bindings
+are built from the same source wherever those toolchains live. CI exercises
+both paths on every push: `package-rpm` (fedora container) and
+`package-deb` (debian container) build and inspect the actual packages.
+
+## Relationship to kutu OS
+
+This is the M3 building block of
+[kutu OS](https://github.com/kutuso/os): the `mempressured` policy daemon and
+eventually applications themselves use these events to shed memory gracefully
+under pressure instead of being killed. The C core has no dependencies beyond
+libc/pthreads, so it ships anywhere — including inside the kutu ISO.
+
+MIT licensed — see [LICENSE](LICENSE).

libmempressure-0.1.0/README.md

@@ -0,0 +1,145 @@
+# libmempressure — a Linux answer to Android's onTrimMemory
+
+Apps on Android never get OOM-killed without warning: the OS sends them
+`onTrimMemory()` callbacks and they shed caches gracefully. Desktop Linux
+just kills them. `libmempressure` closes that gap: it watches the kernel's
+[Pressure Stall Information](https://docs.kernel.org/admin-guide/perf/psi.html)
+and delivers memory-pressure events to your application — in **C, C++, Java
+(JVM) and Python** — so instead of dying under pressure, your app trims.
+
+```
+level       some avg10   what your app should do
+----------- ------------ ------------------------------------
+none        < 5%         business as usual
+low         >= 5%        stop prefetching, trim opportunistically
+moderate    >= 15%       drop object caches, shrink pools
+critical    >= 40%       shed everything, survive
+```
+
+Events are level *changes* only, filtered by hysteresis (consecutive
+readings) so your callback doesn't flap. The monitor reads
+`/proc/pressure/memory` on its own thread; callbacks fire from that thread.
+
+## The C API
+
+```c
+#include <mempressure.h>
+
+static void on_pressure(mp_level_t level, void *userdata) {
+    if (level >= MP_LEVEL_MODERATE) cache_drop_all();
+}
+
+mp_init(NULL);                       /* defaults; zero fields fall back too */
+mp_subscribe(on_pressure, my_app);
+/* ... */
+mp_shutdown();
+```
+
+`mp_config_t` tunes thresholds (5/15/40%), poll interval (0.5s) and
+hysteresis (2 readings); any zero field falls back to its default. See
+[`include/mempressure.h`](include/mempressure.h) for the full contract —
+threading rules, error codes, and the `psi_path` override (used by the test
+suites to drive the monitor from fixture files).
+
+## C++
+
+Header-only RAII wrapper — [`bindings/c++/mempressure.hpp`](bindings/c++/mempressure.hpp):
+
+```cpp
+mp::Monitor monitor;                 /* starts the monitor */
+monitor.subscribe([](mp::Level level) {
+    if (level >= mp::Level::Moderate) cache_drop_all();
+});                                  /* std::function, refcounted lifetime */
+```
+
+## JVM (JNI)
+
+```java
+import io.kutu.mempressure.MemPressure;
+
+MemPressure.start(new MemPressure.Config());
+int handle = MemPressure.subscribe(level -> {
+    if (level >= 2) cache.dropAll();          // 0=none 1=low 2=moderate 3=critical
+});
+MemPressure.unsubscribe(handle);
+MemPressure.stop();
+```
+
+Native side: `bindings/jvm/jni/mempressure_jni.c` (`libmempressure_jni.so`),
+built automatically when a JDK is present. Callbacks arrive on a daemon
+thread attached to the JVM.
+
+## Python
+
+```python
+import mempressure as mp
+
+mp.start()                                    # defaults
+mp.subscribe(lambda level: level >= 2 and cache.drop_all())
+print(mp.psi())                               # {'some_avg10': 0.12, ...}
+mp.stop()
+```
+
+CPython extension (`mempressure` module) built against your interpreter;
+callbacks fire with the GIL acquired from the monitor thread.
+
+## Build and test
+
+```sh
+make test          # cmake build + ctest (C core, C++ binding, JVM binding)
+                   # + python binding tests (needs a venv with pytest, see below)
+```
+
+Details:
+
+```sh
+cmake -S . -B build                # auto-detects Python dev + JDK; skips gracefully
+cmake --build build
+ctest --test-dir build --output-on-failure
+python3 -m venv .venv && .venv/bin/pip install pytest
+.venv/bin/pytest tests/python -q   # (build with -DPython3_EXECUTABLE=.venv/bin/python
+                                   #  if your system python differs from the venv's)
+```
+
+The test suites never require real memory pressure: they point the monitor at
+fixture files via `psi_path` and mutate them to drive level changes. The
+example binary (`mp_example_c`) runs against your real
+`/proc/pressure/memory`.
+
+## Distro packaging (RPM / DEB)
+
+The library is plain C11 + pthreads and installs via CMake's GNUInstallDirs,
+so it lands correctly on any FHS distro (including `/usr/lib64` RPM
+convention). Upstream ships packaging metadata:
+
+- **RPM** (Fedora/RHEL/openSUSE): [`packaging/rpm/libmempressure.spec`](packaging/rpm/libmempressure.spec).
+  Build a tarball and rpmbuild it, or point a COPR at the spec:
+
+  ```sh
+  git archive --prefix=libmempressure-0.1.0/ -o libmempressure-0.1.0.tar.gz HEAD
+  rpmbuild -bb packaging/rpm/libmempressure.spec --define "_sourcedir $PWD"
+  ```
+
+- **DEB** (Debian/Ubuntu): a `debian/` directory with `libmempressure0`
+  (runtime) and `libmempressure-dev` packages, native-format source:
+
+  ```sh
+  sudo apt install build-essential cmake debhelper pkg-config
+  dpkg-buildpackage -us -uc -b
+  ```
+
+Distro packages ship the C core and the header-only C++ binding
+(`-DMP_PYTHON=OFF -DMP_JAVA=OFF` in the build); the Python and JVM bindings
+are built from the same source wherever those toolchains live. CI exercises
+both paths on every push: `package-rpm` (fedora container) and
+`package-deb` (debian container) build and inspect the actual packages.
+
+## Relationship to kutu OS
+
+This is the M3 building block of
+[kutu OS](https://github.com/kutuso/os): the `mempressured` policy daemon and
+eventually applications themselves use these events to shed memory gracefully
+under pressure instead of being killed. The C core has no dependencies beyond
+libc/pthreads, so it ships anywhere — including inside the kutu ISO.
+
+MIT licensed — see [LICENSE](LICENSE).

libmempressure-0.1.0/bindings/python/mempressure_module.c

@@ -0,0 +1,193 @@
+#define PY_SSIZE_T_CLEAN
+
+#include "mempressure.h"
+
+#include <Python.h>
+#include <errno.h>
+
+static PyObject *g_handles = NULL;
+static int g_started = 0;
+
+static void py_trampoline(mp_level_t level, void *userdata) {
+    PyGILState_STATE gstate = PyGILState_Ensure();
+    PyObject *cb = (PyObject *)userdata;
+    PyObject *arg = PyLong_FromLong((long)level);
+    if (arg) {
+        PyObject *result = PyObject_CallFunctionObjArgs(cb, arg, NULL);
+        if (!result) {
+            PyErr_Print();
+        }
+        Py_XDECREF(result);
+        Py_DECREF(arg);
+    }
+    PyGILState_Release(gstate);
+}
+
+static PyObject *py_start(PyObject *self, PyObject *args, PyObject *kwds) {
+    (void)self;
+    double low = 5.0, moderate = 15.0, critical = 40.0, interval = 0.5;
+    int hysteresis = 2;
+    const char *psi_path = NULL;
+    static char *kwlist[] = {"low", "moderate", "critical", "interval", "hysteresis", "psi_path", NULL};
+    if (!PyArg_ParseTupleAndKeywords(args, kwds, "|ddddis", kwlist, &low, &moderate, &critical,
+                                     &interval, &hysteresis, &psi_path)) {
+        return NULL;
+    }
+    mp_config_t cfg = {0};
+    cfg.low_threshold = low;
+    cfg.moderate_threshold = moderate;
+    cfg.critical_threshold = critical;
+    cfg.poll_interval_sec = interval;
+    cfg.hysteresis = hysteresis;
+    cfg.psi_path = psi_path;
+    int rc = mp_init(&cfg);
+    if (rc == -EALREADY) {
+        Py_RETURN_TRUE;
+    }
+    if (rc != 0) {
+        PyErr_Format(PyExc_RuntimeError, "mp_init failed: %d", rc);
+        return NULL;
+    }
+    g_started = 1;
+    Py_RETURN_TRUE;
+}
+
+static PyObject *py_stop(PyObject *self, PyObject *args) {
+    (void)self;
+    (void)args;
+    mp_shutdown();
+    g_started = 0;
+    Py_RETURN_NONE;
+}
+
+static PyObject *py_current_level(PyObject *self, PyObject *args) {
+    (void)self;
+    (void)args;
+    return PyLong_FromLong((long)mp_current_level());
+}
+
+static PyObject *py_level_name(PyObject *self, PyObject *args) {
+    (void)self;
+    int level = 0;
+    if (!PyArg_ParseTuple(args, "i", &level)) {
+        return NULL;
+    }
+    return PyUnicode_FromString(mp_level_name((mp_level_t)level));
+}
+
+static PyObject *py_psi(PyObject *self, PyObject *args) {
+    (void)self;
+    (void)args;
+    mp_psi_t psi = {0};
+    int rc = mp_psi(&psi);
+    if (rc != 0) {
+        PyErr_Format(PyExc_RuntimeError, "mp_psi failed: %d (not started?)", rc);
+        return NULL;
+    }
+    return Py_BuildValue("{s:d,s:d,s:d,s:d,s:d,s:d}", "some_avg10", psi.some_avg10,
+                         "some_avg60", psi.some_avg60, "some_avg300", psi.some_avg300,
+                         "full_avg10", psi.full_avg10, "full_avg60", psi.full_avg60,
+                         "full_avg300", psi.full_avg300);
+}
+
+static PyObject *py_subscribe(PyObject *self, PyObject *callback) {
+    (void)self;
+    if (!PyCallable_Check(callback)) {
+        PyErr_SetString(PyExc_TypeError, "callback must be callable");
+        return NULL;
+    }
+    if (!g_started) {
+        int rc = mp_init(NULL);
+        if (rc != 0 && rc != -EALREADY) {
+            PyErr_Format(PyExc_RuntimeError, "mp_init failed: %d", rc);
+            return NULL;
+        }
+        g_started = 1;
+    }
+    Py_INCREF(callback);
+    int handle = mp_subscribe(py_trampoline, callback);
+    if (handle < 0) {
+        Py_DECREF(callback);
+        PyErr_Format(PyExc_RuntimeError, "mp_subscribe failed: %d", handle);
+        return NULL;
+    }
+    PyObject *key = PyLong_FromLong(handle);
+    PyDict_SetItem(g_handles, key, callback);
+    Py_DECREF(key);
+    Py_DECREF(callback);  // dict owns the strong ref now
+    return PyLong_FromLong(handle);
+}
+
+static PyObject *py_unsubscribe(PyObject *self, PyObject *args) {
+    (void)self;
+    int handle = 0;
+    if (!PyArg_ParseTuple(args, "i", &handle)) {
+        return NULL;
+    }
+    int rc = mp_unsubscribe(handle);
+    if (rc == -ENOENT) {
+        PyErr_SetString(PyExc_ValueError, "unknown handle");
+        return NULL;
+    }
+    PyObject *key = PyLong_FromLong(handle);
+    PyObject *cb = PyDict_GetItemWithError(g_handles, key);
+    if (cb) {
+        Py_INCREF(cb);
+        PyDict_DelItem(g_handles, key);
+        Py_DECREF(cb);
+    } else if (PyErr_Occurred()) {
+        PyErr_Clear();
+    }
+    Py_DECREF(key);
+    Py_RETURN_NONE;
+}
+
+static PyMethodDef methods[] = {
+    {"start", (PyCFunction)py_start, METH_VARARGS | METH_KEYWORDS,
+     "start(low=5.0, moderate=15.0, critical=40.0, interval=0.5, hysteresis=2, psi_path=None)\n\n"
+     "Start the pressure monitor. Re-starting with a live monitor is a no-op."},
+    {"stop", py_stop, METH_NOARGS, "Stop the monitor and release everything."},
+    {"current_level", py_current_level, METH_NOARGS, "Current pressure level (0..3)."},
+    {"level_name", py_level_name, METH_VARARGS, "Name of a level code."},
+    {"psi", py_psi, METH_NOARGS, "Last observed PSI values as a dict."},
+    {"subscribe", py_subscribe, METH_O, "subscribe(callback) -> handle; fires on level change."},
+    {"unsubscribe", py_unsubscribe, METH_VARARGS, "unsubscribe(handle)."},
+    {NULL, NULL, 0, NULL},
+};
+
+static void free_module_state(void *module) {
+    (void)module;
+    Py_CLEAR(g_handles);
+}
+
+static struct PyModuleDef module_def = {
+    PyModuleDef_HEAD_INIT,
+    "mempressure",
+    "Memory-pressure events from the kernel's PSI, an onTrimMemory for Linux.",
+    -1,
+    methods,
+    NULL,
+    NULL,
+    NULL,
+    free_module_state,
+};
+
+PyMODINIT_FUNC PyInit_mempressure(void) {
+    g_handles = PyDict_New();
+    if (!g_handles) {
+        return NULL;
+    }
+    PyObject *module = PyModule_Create(&module_def);
+    if (!module) {
+        Py_DECREF(g_handles);
+        return NULL;
+    }
+    PyModule_AddStringConstant(module, "__version__", MP_VERSION);
+    PyObject *levels = PyDict_New();
+    PyDict_SetItemString(levels, "NONE", PyLong_FromLong(MP_LEVEL_NONE));
+    PyDict_SetItemString(levels, "LOW", PyLong_FromLong(MP_LEVEL_LOW));
+    PyDict_SetItemString(levels, "MODERATE", PyLong_FromLong(MP_LEVEL_MODERATE));
+    PyDict_SetItemString(levels, "CRITICAL", PyLong_FromLong(MP_LEVEL_CRITICAL));
+    PyModule_AddObject(module, "LEVELS", levels);
+    return module;
+}

libmempressure-0.1.0/include/mempressure.h

@@ -0,0 +1,81 @@
+/*
+ * mempressure - a Linux answer to Android's onTrimMemory
+ *
+ * Subscribe your application to memory-pressure events derived from the
+ * kernel's Pressure Stall Information (PSI). Instead of being killed by the
+ * OOM killer (or userspace oomd), applications learn that memory is getting
+ * tight and shed caches gracefully.
+ */
+#ifndef MEMPRESSURE_H
+#define MEMPRESSURE_H
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define MP_VERSION "0.1.0"
+#define MP_PSI_PATH_DEFAULT "/proc/pressure/memory"
+
+typedef enum {
+    MP_LEVEL_NONE = 0,     /* no meaningful stall time */
+    MP_LEVEL_LOW = 1,      /* some reclaim happening; trim opportunistically */
+    MP_LEVEL_MODERATE = 2, /* tasks visibly stalled; drop caches */
+    MP_LEVEL_CRITICAL = 3  /* heavy stalls; shed everything, survive */
+} mp_level_t;
+
+typedef struct {
+    double some_avg10;
+    double some_avg60;
+    double some_avg300;
+    double full_avg10;
+    double full_avg60;
+    double full_avg300;
+} mp_psi_t;
+
+typedef void (*mp_callback_t)(mp_level_t level, void *userdata);
+
+typedef struct {
+    double low_threshold;      /* "some" avg10 in percent; default 5.0 */
+    double moderate_threshold; /* default 15.0 */
+    double critical_threshold; /* default 40.0 */
+    double poll_interval_sec;  /* monitor tick; default 0.5 */
+    int hysteresis;            /* consecutive readings before a level change
+                                  fires; default 2 */
+    const char *psi_path;      /* default /proc/pressure/memory; override for
+                                  tests or containers */
+} mp_config_t;
+
+/* Start the monitor thread. cfg may be NULL for all defaults; zero fields in
+ * cfg also fall back to their defaults (so partial overrides just work).
+ * Returns 0, or -EALREADY if already running, -EINVAL for a bad config. */
+int mp_init(const mp_config_t *cfg);
+
+/* Stop the monitor thread and release everything. Idempotent. */
+int mp_shutdown(void);
+
+/* Current (post-hysteresis) pressure level. Valid after mp_init. */
+mp_level_t mp_current_level(void);
+
+/* Last observed PSI values; returns 0, or -EPERM if mp_init was not called. */
+int mp_psi(mp_psi_t *out);
+
+/* Register a callback fired from the monitor thread whenever the level
+ * changes. Returns a handle (> 0), or -EINVAL (NULL cb), -EPERM (not
+ * initialized). Callbacks must not block; do not call mp_shutdown from a
+ * callback. */
+int mp_subscribe(mp_callback_t cb, void *userdata);
+
+/* Remove a subscription. Returns 0, or -ENOENT. Safe to call from within a
+ * callback for any handle except the one currently being dispatched. */
+int mp_unsubscribe(int handle);
+
+const char *mp_level_name(mp_level_t level);
+const char *mp_version(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* MEMPRESSURE_H */

libmempressure-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "libmempressure"
+version = "0.1.0"
+description = "Memory-pressure events from kernel PSI: an onTrimMemory for Linux (Python binding)"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "kutu OS contributors" }]
+requires-python = ">=3.10"
+keywords = ["memory", "psi", "pressure", "linux", "oom", "swap", "performance"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: C",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: System :: Operating System Kernels :: Linux",
+]
+
+[project.urls]
+Homepage = "https://kutu.so"
+Repository = "https://github.com/kutuso/libmempressure"
+Documentation = "https://kutu.so/#/LIBMEMPRESSURE.md"

libmempressure-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

libmempressure-0.1.0/setup.py

@@ -0,0 +1,15 @@
+from setuptools import Extension, setup
+
+setup(
+    ext_modules=[
+        Extension(
+            "mempressure",
+            sources=[
+                "src/mempressure.c",
+                "bindings/python/mempressure_module.c",
+            ],
+            include_dirs=["include"],
+            define_macros=[("_GNU_SOURCE", "1")],
+        )
+    ]
+)

libmempressure-0.1.0/src/libmempressure.egg-info/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: libmempressure
+Version: 0.1.0
+Summary: Memory-pressure events from kernel PSI: an onTrimMemory for Linux (Python binding)
+Author: kutu OS contributors
+License-Expression: MIT
+Project-URL: Homepage, https://kutu.so
+Project-URL: Repository, https://github.com/kutuso/libmempressure
+Project-URL: Documentation, https://kutu.so/#/LIBMEMPRESSURE.md
+Keywords: memory,psi,pressure,linux,oom,swap,performance
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Operating System Kernels :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# libmempressure — a Linux answer to Android's onTrimMemory
+
+Apps on Android never get OOM-killed without warning: the OS sends them
+`onTrimMemory()` callbacks and they shed caches gracefully. Desktop Linux
+just kills them. `libmempressure` closes that gap: it watches the kernel's
+[Pressure Stall Information](https://docs.kernel.org/admin-guide/perf/psi.html)
+and delivers memory-pressure events to your application — in **C, C++, Java
+(JVM) and Python** — so instead of dying under pressure, your app trims.
+
+```
+level       some avg10   what your app should do
+----------- ------------ ------------------------------------
+none        < 5%         business as usual
+low         >= 5%        stop prefetching, trim opportunistically
+moderate    >= 15%       drop object caches, shrink pools
+critical    >= 40%       shed everything, survive
+```
+
+Events are level *changes* only, filtered by hysteresis (consecutive
+readings) so your callback doesn't flap. The monitor reads
+`/proc/pressure/memory` on its own thread; callbacks fire from that thread.
+
+## The C API
+
+```c
+#include <mempressure.h>
+
+static void on_pressure(mp_level_t level, void *userdata) {
+    if (level >= MP_LEVEL_MODERATE) cache_drop_all();
+}
+
+mp_init(NULL);                       /* defaults; zero fields fall back too */
+mp_subscribe(on_pressure, my_app);
+/* ... */
+mp_shutdown();
+```
+
+`mp_config_t` tunes thresholds (5/15/40%), poll interval (0.5s) and
+hysteresis (2 readings); any zero field falls back to its default. See
+[`include/mempressure.h`](include/mempressure.h) for the full contract —
+threading rules, error codes, and the `psi_path` override (used by the test
+suites to drive the monitor from fixture files).
+
+## C++
+
+Header-only RAII wrapper — [`bindings/c++/mempressure.hpp`](bindings/c++/mempressure.hpp):
+
+```cpp
+mp::Monitor monitor;                 /* starts the monitor */
+monitor.subscribe([](mp::Level level) {
+    if (level >= mp::Level::Moderate) cache_drop_all();
+});                                  /* std::function, refcounted lifetime */
+```
+
+## JVM (JNI)
+
+```java
+import io.kutu.mempressure.MemPressure;
+
+MemPressure.start(new MemPressure.Config());
+int handle = MemPressure.subscribe(level -> {
+    if (level >= 2) cache.dropAll();          // 0=none 1=low 2=moderate 3=critical
+});
+MemPressure.unsubscribe(handle);
+MemPressure.stop();
+```
+
+Native side: `bindings/jvm/jni/mempressure_jni.c` (`libmempressure_jni.so`),
+built automatically when a JDK is present. Callbacks arrive on a daemon
+thread attached to the JVM.
+
+## Python
+
+```python
+import mempressure as mp
+
+mp.start()                                    # defaults
+mp.subscribe(lambda level: level >= 2 and cache.drop_all())
+print(mp.psi())                               # {'some_avg10': 0.12, ...}
+mp.stop()
+```
+
+CPython extension (`mempressure` module) built against your interpreter;
+callbacks fire with the GIL acquired from the monitor thread.
+
+## Build and test
+
+```sh
+make test          # cmake build + ctest (C core, C++ binding, JVM binding)
+                   # + python binding tests (needs a venv with pytest, see below)
+```
+
+Details:
+
+```sh
+cmake -S . -B build                # auto-detects Python dev + JDK; skips gracefully
+cmake --build build
+ctest --test-dir build --output-on-failure
+python3 -m venv .venv && .venv/bin/pip install pytest
+.venv/bin/pytest tests/python -q   # (build with -DPython3_EXECUTABLE=.venv/bin/python
+                                   #  if your system python differs from the venv's)
+```
+
+The test suites never require real memory pressure: they point the monitor at
+fixture files via `psi_path` and mutate them to drive level changes. The
+example binary (`mp_example_c`) runs against your real
+`/proc/pressure/memory`.
+
+## Distro packaging (RPM / DEB)
+
+The library is plain C11 + pthreads and installs via CMake's GNUInstallDirs,
+so it lands correctly on any FHS distro (including `/usr/lib64` RPM
+convention). Upstream ships packaging metadata:
+
+- **RPM** (Fedora/RHEL/openSUSE): [`packaging/rpm/libmempressure.spec`](packaging/rpm/libmempressure.spec).
+  Build a tarball and rpmbuild it, or point a COPR at the spec:
+
+  ```sh
+  git archive --prefix=libmempressure-0.1.0/ -o libmempressure-0.1.0.tar.gz HEAD
+  rpmbuild -bb packaging/rpm/libmempressure.spec --define "_sourcedir $PWD"
+  ```
+
+- **DEB** (Debian/Ubuntu): a `debian/` directory with `libmempressure0`
+  (runtime) and `libmempressure-dev` packages, native-format source:
+
+  ```sh
+  sudo apt install build-essential cmake debhelper pkg-config
+  dpkg-buildpackage -us -uc -b
+  ```
+
+Distro packages ship the C core and the header-only C++ binding
+(`-DMP_PYTHON=OFF -DMP_JAVA=OFF` in the build); the Python and JVM bindings
+are built from the same source wherever those toolchains live. CI exercises
+both paths on every push: `package-rpm` (fedora container) and
+`package-deb` (debian container) build and inspect the actual packages.
+
+## Relationship to kutu OS
+
+This is the M3 building block of
+[kutu OS](https://github.com/kutuso/os): the `mempressured` policy daemon and
+eventually applications themselves use these events to shed memory gracefully
+under pressure instead of being killed. The C core has no dependencies beyond
+libc/pthreads, so it ships anywhere — including inside the kutu ISO.
+
+MIT licensed — see [LICENSE](LICENSE).

libmempressure-0.1.0/src/libmempressure.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+bindings/python/mempressure_module.c
+include/mempressure.h
+src/mempressure.c
+src/libmempressure.egg-info/PKG-INFO
+src/libmempressure.egg-info/SOURCES.txt
+src/libmempressure.egg-info/dependency_links.txt
+src/libmempressure.egg-info/top_level.txt

libmempressure-0.1.0/src/libmempressure.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

libmempressure-0.1.0/src/libmempressure.egg-info/top_level.txt

@@ -0,0 +1 @@
+mempressure

libmempressure-0.1.0/src/mempressure.c

@@ -0,0 +1,341 @@
+#define _GNU_SOURCE
+
+#include "mempressure.h"
+
+#include <errno.h>
+#include <pthread.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+
+#define MP_DEFAULT_PSI_PATH MP_PSI_PATH_DEFAULT
+
+typedef struct sub {
+    int handle;
+    mp_callback_t cb;
+    void *userdata;
+    struct sub *next;
+} sub_t;
+
+typedef struct {
+    mp_callback_t cb;
+    void *userdata;
+} sub_snapshot_t;
+
+static struct {
+    pthread_mutex_t lock;
+    pthread_t thread;
+    int started;
+    int running;
+    mp_config_t cfg;
+    char *psi_path;
+    mp_psi_t psi;
+    mp_level_t level;
+    mp_level_t pending;
+    int pending_count;
+    int next_handle;
+    sub_t *subs;
+} g = {
+    .lock = PTHREAD_MUTEX_INITIALIZER,
+};
+
+static void sleep_sec(double seconds) {
+    struct timespec ts = {
+        .tv_sec = (time_t)seconds,
+        .tv_nsec = (long)((seconds - (double)(time_t)seconds) * 1e9),
+    };
+    nanosleep(&ts, NULL);
+}
+
+static int parse_line(const char *line, const char *kind, mp_psi_t *out) {
+    if (strncmp(line, kind, strlen(kind)) != 0) {
+        return 0;
+    }
+    const char *cursor = line + strlen(kind);
+    while (*cursor == ' ') cursor++;
+    char key[8];
+    double value;
+    int matched = 0;
+    while (sscanf(cursor, "%7[a-z0-9_]=%lf", key, &value) == 2) {
+        if (strcmp(kind, "some") == 0) {
+            if (strcmp(key, "avg10") == 0) { out->some_avg10 = value; matched++; }
+            else if (strcmp(key, "avg60") == 0) { out->some_avg60 = value; matched++; }
+            else if (strcmp(key, "avg300") == 0) { out->some_avg300 = value; matched++; }
+        } else {
+            if (strcmp(key, "avg10") == 0) { out->full_avg10 = value; matched++; }
+            else if (strcmp(key, "avg60") == 0) { out->full_avg60 = value; matched++; }
+            else if (strcmp(key, "avg300") == 0) { out->full_avg300 = value; matched++; }
+        }
+        while (*cursor && *cursor != ' ') cursor++;
+        while (*cursor == ' ') cursor++;
+        if (!*cursor) break;
+    }
+    return matched == 3;
+}
+
+static int read_psi(const char *path, mp_psi_t *out) {
+    FILE *fh = fopen(path, "r");
+    if (!fh) {
+        return -errno;
+    }
+    memset(out, 0, sizeof *out);
+    char line[256];
+    int have_some = 0;
+    int have_full = 0;
+    while (fgets(line, sizeof line, fh)) {
+        if (parse_line(line, "some", out)) have_some = 1;
+        if (parse_line(line, "full", out)) have_full = 1;
+    }
+    fclose(fh);
+    return (have_some && have_full) ? 0 : -EIO;
+}
+
+static mp_level_t level_for(const mp_psi_t *psi, const mp_config_t *cfg) {
+    double some = psi->some_avg10;
+    if (some >= cfg->critical_threshold) return MP_LEVEL_CRITICAL;
+    if (some >= cfg->moderate_threshold) return MP_LEVEL_MODERATE;
+    if (some >= cfg->low_threshold) return MP_LEVEL_LOW;
+    return MP_LEVEL_NONE;
+}
+
+typedef struct fire {
+    sub_snapshot_t *subs;
+    int count;
+    mp_level_t level;
+} fire_t;
+
+static void *monitor_main(void *arg) {
+    (void)arg;
+    const mp_config_t cfg = g.cfg;
+    const char *psi_path = g.psi_path;
+    while (1) {
+        pthread_mutex_lock(&g.lock);
+        int running = g.running;
+        pthread_mutex_unlock(&g.lock);
+        if (!running) {
+            break;
+        }
+
+        mp_psi_t psi;
+        if (read_psi(psi_path, &psi) == 0) {
+            mp_level_t reading = level_for(&psi, &cfg);
+
+            pthread_mutex_lock(&g.lock);
+            g.psi = psi;
+            if (reading != g.pending) {
+                g.pending = reading;
+                g.pending_count = 1;
+            } else if (g.pending_count < cfg.hysteresis) {
+                g.pending_count++;
+            }
+
+            int changed = 0;
+            mp_level_t fire_level = g.level;
+            if (g.pending_count >= cfg.hysteresis && g.pending != g.level) {
+                g.level = g.pending;
+                fire_level = g.level;
+                changed = 1;
+            }
+
+            fire_t fire = {NULL, 0, fire_level};
+            if (changed) {
+                int n = 0;
+                for (sub_t *s = g.subs; s; s = s->next) n++;
+                if (n > 0) {
+                    fire.subs = malloc((size_t)n * sizeof *fire.subs);
+                    if (fire.subs) {
+                        fire.count = n;
+                        int i = 0;
+                        for (sub_t *s = g.subs; s; s = s->next) {
+                            fire.subs[i].cb = s->cb;
+                            fire.subs[i].userdata = s->userdata;
+                            i++;
+                        }
+                    }
+                }
+            }
+            pthread_mutex_unlock(&g.lock);
+
+            if (fire.subs) {
+                for (int i = 0; i < fire.count; i++) {
+                    fire.subs[i].cb(fire.level, fire.subs[i].userdata);
+                }
+                free(fire.subs);
+            }
+        }
+        sleep_sec(cfg.poll_interval_sec);
+    }
+    return NULL;
+}
+
+static int config_valid(const mp_config_t *cfg) {
+    if (cfg->low_threshold < 0 || cfg->moderate_threshold <= cfg->low_threshold ||
+        cfg->critical_threshold <= cfg->moderate_threshold || cfg->critical_threshold > 100) {
+        return 0;
+    }
+    if (!(cfg->poll_interval_sec > 0) || cfg->hysteresis < 1) {
+        return 0;
+    }
+    return 1;
+}
+
+static void config_fill_defaults(mp_config_t *cfg) {
+    if (cfg->low_threshold == 0 && cfg->moderate_threshold == 0 && cfg->critical_threshold == 0) {
+        cfg->low_threshold = 5.0;
+        cfg->moderate_threshold = 15.0;
+        cfg->critical_threshold = 40.0;
+    }
+    if (!(cfg->poll_interval_sec > 0)) {
+        cfg->poll_interval_sec = 0.5;
+    }
+    if (cfg->hysteresis < 1) {
+        cfg->hysteresis = 2;
+    }
+}
+
+int mp_init(const mp_config_t *cfg) {
+    pthread_mutex_lock(&g.lock);
+    if (g.started) {
+        pthread_mutex_unlock(&g.lock);
+        return -EALREADY;
+    }
+    memset(&g.cfg, 0, sizeof g.cfg);
+    if (cfg) {
+        g.cfg = *cfg;
+    }
+    config_fill_defaults(&g.cfg);
+    if (!config_valid(&g.cfg)) {
+        pthread_mutex_unlock(&g.lock);
+        return -EINVAL;
+    }
+    g.psi_path = strdup(cfg && cfg->psi_path ? cfg->psi_path : MP_DEFAULT_PSI_PATH);
+    if (!g.psi_path) {
+        pthread_mutex_unlock(&g.lock);
+        return -ENOMEM;
+    }
+    g.psi = (mp_psi_t){0};
+    g.level = MP_LEVEL_NONE;
+    g.pending = MP_LEVEL_NONE;
+    g.pending_count = 0;
+    g.next_handle = 1;
+    g.subs = NULL;
+    g.running = 1;
+    g.started = 1;
+    if (pthread_create(&g.thread, NULL, monitor_main, NULL) != 0) {
+        free(g.psi_path);
+        g.psi_path = NULL;
+        g.started = 0;
+        g.running = 0;
+        pthread_mutex_unlock(&g.lock);
+        return -errno;
+    }
+    pthread_mutex_unlock(&g.lock);
+    return 0;
+}
+
+int mp_shutdown(void) {
+    pthread_mutex_lock(&g.lock);
+    if (!g.started) {
+        pthread_mutex_unlock(&g.lock);
+        return 0;
+    }
+    g.running = 0;
+    pthread_t thread = g.thread;
+    sub_t *subs = g.subs;
+    g.subs = NULL;
+    char *psi_path = g.psi_path;
+    g.psi_path = NULL;
+    g.started = 0;
+    pthread_mutex_unlock(&g.lock);
+
+    pthread_join(thread, NULL);
+    while (subs) {
+        sub_t *next = subs->next;
+        free(subs);
+        subs = next;
+    }
+    free(psi_path);
+    return 0;
+}
+
+mp_level_t mp_current_level(void) {
+    pthread_mutex_lock(&g.lock);
+    mp_level_t level = g.level;
+    pthread_mutex_unlock(&g.lock);
+    return level;
+}
+
+int mp_psi(mp_psi_t *out) {
+    if (!out) {
+        return -EINVAL;
+    }
+    pthread_mutex_lock(&g.lock);
+    if (!g.started) {
+        pthread_mutex_unlock(&g.lock);
+        return -EPERM;
+    }
+    *out = g.psi;
+    pthread_mutex_unlock(&g.lock);
+    return 0;
+}
+
+int mp_subscribe(mp_callback_t cb, void *userdata) {
+    if (!cb) {
+        return -EINVAL;
+    }
+    pthread_mutex_lock(&g.lock);
+    if (!g.started) {
+        pthread_mutex_unlock(&g.lock);
+        return -EPERM;
+    }
+    sub_t *sub = malloc(sizeof *sub);
+    if (!sub) {
+        pthread_mutex_unlock(&g.lock);
+        return -ENOMEM;
+    }
+    sub->handle = g.next_handle++;
+    sub->cb = cb;
+    sub->userdata = userdata;
+    sub->next = g.subs;
+    g.subs = sub;
+    int handle = sub->handle;
+    pthread_mutex_unlock(&g.lock);
+    return handle;
+}
+
+int mp_unsubscribe(int handle) {
+    pthread_mutex_lock(&g.lock);
+    sub_t **cursor = &g.subs;
+    while (*cursor) {
+        if ((*cursor)->handle == handle) {
+            sub_t *dead = *cursor;
+            *cursor = dead->next;
+            free(dead);
+            pthread_mutex_unlock(&g.lock);
+            return 0;
+        }
+        cursor = &(*cursor)->next;
+    }
+    pthread_mutex_unlock(&g.lock);
+    return -ENOENT;
+}
+
+const char *mp_level_name(mp_level_t level) {
+    switch (level) {
+    case MP_LEVEL_NONE:
+        return "none";
+    case MP_LEVEL_LOW:
+        return "low";
+    case MP_LEVEL_MODERATE:
+        return "moderate";
+    case MP_LEVEL_CRITICAL:
+        return "critical";
+    default:
+        return "unknown";
+    }
+}
+
+const char *mp_version(void) {
+    return MP_VERSION;
+}