Resource Utils

GitHub Link to Code.

Utilities for applying process-level resource limits.

These limits are best-effort and platform-dependent. Requires psutil and threadpoolctl for portable process priority, I/O priority, CPU affinity, and BLAS/OpenMP thread limiting.

class mdxplain.utils.resource_utils.ResourceUtils

Utility class for best-effort process-level resource limits.

static recommend_cpu_affinity(reserve_cores: int = 2) → List[int] | None

Recommend a CPU affinity mask leaving a number of cores free.

Parameters

reserve_coresint, default=2: Number of cores to leave unused for system responsiveness. The resulting affinity always keeps at least one core, even when reserve_cores is large relative to the allocation.

Returns

list of int or None: Recommended CPU affinity list, or None if unavailable. The list is derived from the currently allowed CPUs (e.g., cgroups on HPC), so it will not exceed the scheduler allocation.

Notes

This does not apply the affinity; it only calculates the recommended mask. Use apply_process_limits to enforce the recommendation.

static apply_auto_limits(reserve_cores: int = 2, nice: int | None = 15, io_priority: str | None = None) → Dict[str, Any]

Apply recommended CPU affinity plus optional nice/I/O priority.

Parameters

reserve_coresint, default=2: Number of cores to leave free.
niceint, optional: POSIX nice value (or Windows priority mapping). Use 0 for normal priority. Positive values yield to the desktop or scheduler. The default of 15 is intentionally conservative to keep the system responsive during heavy I/O workloads.
io_prioritystr, optional: I/O priority hint (“idle”, “low”, “normal”, “high”). Use “low” when working with large memmaps to reduce I/O starvation.

Returns

dict: Dictionary containing applied values and any errors encountered.

Notes

This is a convenience helper that combines recommend_cpu_affinity and apply_process_limits. It is best called early in a process before heavy compute starts.

static apply_blas_thread_limits(max_threads: int | None) → Dict[str, Any]

Apply global BLAS/OpenMP thread limits for the current process.

Parameters

max_threadsint or None: Maximum number of BLAS/OpenMP threads. None resets to defaults. Set to the effective CPU affinity size to avoid oversubscription.

Returns

dict: Dictionary containing applied values and any errors encountered.

Notes

This uses threadpoolctl to update active BLAS/OpenMP thread pools. The limit is process-wide and persistent until reset or changed. It does not alter environment variables and does not interrupt already-running compute kernels.

When using joblib or other parallel backends (n_jobs > 1), prefer keeping this limit at the effective CPU count and rely on per-algorithm auto_limit_blas logic to drop BLAS threads to 1 for those workloads.

static apply_process_limits(nice: int | None = None, io_priority: str | None = None, cpu_affinity: Sequence[int] | None = None) → Dict[str, Any]

Apply process-level limits for CPU priority, I/O priority, and affinity.

Parameters

niceint, optional: POSIX nice value. On Windows, maps to a best-effort priority class.
io_prioritystr, optional: I/O priority hint (“idle”, “low”, “normal”, “high”). Best-effort. Some platforms ignore this setting or require elevated privileges.
cpu_affinitysequence of int, optional: CPU affinity mask (list of CPU indices). Best-effort.

Returns

dict: Dictionary containing applied values and any errors encountered.

Notes

CPU affinity constrains where all threads in this process may run. This is the most reliable way to keep a few cores free for system responsiveness. I/O priority is useful for large memmap workloads, but exact behavior varies by OS and filesystem.

static tune_memmap(array: Any, strategy: str, start_offset: int = 0, length: int = 0) → Dict[str, Any]

Apply a best-effort madvise hint to a memmap (or memmap-backed view).

Parameters

arrayAny: Memmap (or ndarray view backed by a memmap).
strategystr: One of: "sequential", "random", "dontneed".
start_offsetint: Byte offset for range-based hints. Default 0 (full mapping).
lengthint: Byte length for range-based hints. For known mapping sizes, values <=0 are interpreted as “until end of mapping”.

Returns

dict: {"strategy": ..., "applied": bool, "errors": [..]}.