Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 18 additions & 4 deletions docs/src/content/docs/reference/runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,24 @@ BEAM.threads() # the limit in force (0: the system's choice)
BEAM.effective_threads() # what a parallel step would start right now
```

BEAM uses all available cores by default, or `OMP_NUM_THREADS` if it is set. `set_threads` is
a hard limit, which is what you want inside a job scheduler or next to another parallel step. It
applies to every model in the process; `set_threads(0)` restores the default. Set it before
starting work, not while another thread is computing.
By default BEAM picks the width itself, from how busy the machine is and from where its own
work stops scaling — on a quiet workstation that is up to eight threads, and on a shared node
with little free it is far fewer, which is the difference between a job that runs and one that
thrashes. `OMP_NUM_THREADS`, if you set it, decides instead: BEAM treats it as your instruction
and stands aside.

`set_threads` is a hard limit, which is what you want inside a job scheduler or next to another
parallel step. It applies to every model in the process; `set_threads(0)` restores the default.
Set it before starting work, not while another thread is computing.

```python
BEAM.parallel_plan() # what the default resolved to, and from what
```

For a benchmark or a figure you want to reproduce exactly, pin the machine estimate with the
`BEAM_AVAILABLE_CORES` environment variable; the plan then depends only on your own settings
rather than on what else happened to be running. `parallel_plan()` reports the width and the
inputs it came from, so a surprising thread count can be explained rather than guessed at.

**Results do not depend on the number of threads.** Every sum is taken in a fixed order, so one
thread and sixteen give the same answer, bit for bit.
Expand Down
190 changes: 190 additions & 0 deletions src/native/core/avail.c
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,27 @@
#include <sched.h>
#endif

/*
* The sampled estimate, for the platforms with no /proc. See avail.h for why
* the quantity is competitors rather than load, and why that costs a second
* clock read.
*/
#if defined(__APPLE__)
#include <mach/mach.h>
#include <sys/resource.h>
#include <sys/time.h>
#include <time.h>
#include <unistd.h>
#elif defined(_WIN32)
#include <windows.h>
#endif

#ifdef _MSC_VER
#define TLS __declspec(thread)
#else
#define TLS _Thread_local
#endif

/* ── Parsers ─────────────────────────────────────────────────── */

int beam_parse_nr_running(const char *loadavg_text) {
Expand Down Expand Up @@ -92,6 +113,44 @@ int beam_available_from(int allowed, int nr_running) {
return avail < 1 ? 1 : avail;
}

int beam_competitors_from_cpu_time(uint64_t sys_busy_ns, uint64_t own_ns,
uint64_t wall_ns, int allowed) {
if (allowed < 1) allowed = 1;
if (wall_ns < BEAM_AVAIL_MIN_WINDOW_NS) return -1;
/*
* Our own time can exceed the system total across a non-atomic pair of
* reads. Equal means the machine ran nothing but us.
*/
if (sys_busy_ns <= own_ns) return 1;
const uint64_t other = sys_busy_ns - own_ns;
/* Ceiling: half a core of competition is one competitor, not none. */
uint64_t cores = (other + wall_ns - 1u) / wall_ns;
if (cores > (uint64_t)allowed) cores = (uint64_t)allowed;
return (int)cores + 1;
}

int beam_competitors_from_samples(BeamAvailSample *prev, uint64_t sys,
uint64_t own, uint64_t wall, int allowed) {
if (!prev) return -1;

if (!prev->have) { /* rule 1 */
prev->sys = sys; prev->own = own; prev->wall = wall; prev->have = 1;
return -1;
}
if (wall <= prev->wall || sys < prev->sys || own < prev->own) { /* rule 3 */
prev->sys = sys; prev->own = own; prev->wall = wall;
return -1;
}
const uint64_t window = wall - prev->wall;
if (window < BEAM_AVAIL_MIN_WINDOW_NS) return -1; /* rule 2 */

const int nr = beam_competitors_from_cpu_time(sys - prev->sys,
own - prev->own,
window, allowed);
prev->sys = sys; prev->own = own; prev->wall = wall;
return nr;
}

/* ── Reading the machine ─────────────────────────────────────── */

int beam_cores_present(void) {
Expand Down Expand Up @@ -146,6 +205,129 @@ int beam_allowed_cores(void) {
return allowed;
}

#if defined(__APPLE__) || defined(_WIN32)
/*
* Busy CPU time across every CPU, our own process's CPU time, and a monotonic
* wall clock -- all in nanoseconds, so the pure arithmetic above never sees a
* platform's tick unit. Each returns 0 on failure, and a failed read means
* "unknown", which is the existing safe fallback rather than a special case.
*/
static int read_system_busy_ns(uint64_t *out) {
#if defined(__APPLE__)
host_cpu_load_info_data_t info;
mach_msg_type_number_t count = HOST_CPU_LOAD_INFO_COUNT;
/*
* mach_host_self() hands out a send right, and this runs at every entry
* point: without the deallocate it leaks one Mach port reference per BEAM
* call, which no test would notice and a long-lived process would.
*/
const host_t host = mach_host_self();
const kern_return_t kr = host_statistics(host, HOST_CPU_LOAD_INFO,
(host_info_t)&info, &count);
mach_port_deallocate(mach_task_self(), host);
if (kr != KERN_SUCCESS) return 0;
/* HOST_CPU_LOAD_INFO is already summed over the CPUs. Idle is excluded. */
const uint64_t ticks = (uint64_t)info.cpu_ticks[CPU_STATE_USER]
+ (uint64_t)info.cpu_ticks[CPU_STATE_SYSTEM]
+ (uint64_t)info.cpu_ticks[CPU_STATE_NICE];
const long hz = sysconf(_SC_CLK_TCK);
if (hz <= 0) return 0;
*out = ticks * (1000000000ull / (uint64_t)hz);
return 1;
#else
FILETIME idle, kernel, user;
if (!GetSystemTimes(&idle, &kernel, &user)) return 0;
ULARGE_INTEGER i, k, u;
i.LowPart = idle.dwLowDateTime; i.HighPart = idle.dwHighDateTime;
k.LowPart = kernel.dwLowDateTime; k.HighPart = kernel.dwHighDateTime;
u.LowPart = user.dwLowDateTime; u.HighPart = user.dwHighDateTime;
/* Kernel time INCLUDES idle, so busy is kernel + user - idle. */
const uint64_t total = (k.QuadPart + u.QuadPart) * 100ull; /* 100-ns units */
const uint64_t spare = i.QuadPart * 100ull;
*out = total > spare ? total - spare : 0ull;
return 1;
#endif
}

static int read_own_cpu_ns(uint64_t *out) {
#if defined(__APPLE__)
struct rusage ru;
if (getrusage(RUSAGE_SELF, &ru) != 0) return 0;
*out = (uint64_t)ru.ru_utime.tv_sec * 1000000000ull
+ (uint64_t)ru.ru_utime.tv_usec * 1000ull
+ (uint64_t)ru.ru_stime.tv_sec * 1000000000ull
+ (uint64_t)ru.ru_stime.tv_usec * 1000ull;
return 1;
#else
FILETIME created, exited, kernel, user;
if (!GetProcessTimes(GetCurrentProcess(), &created, &exited,
&kernel, &user)) return 0;
ULARGE_INTEGER k, u;
k.LowPart = kernel.dwLowDateTime; k.HighPart = kernel.dwHighDateTime;
u.LowPart = user.dwLowDateTime; u.HighPart = user.dwHighDateTime;
*out = (k.QuadPart + u.QuadPart) * 100ull;
return 1;
#endif
}

static int read_wall_ns(uint64_t *out) {
#if defined(__APPLE__)
struct timespec ts;
if (clock_gettime(CLOCK_MONOTONIC, &ts) != 0) return 0;
*out = (uint64_t)ts.tv_sec * 1000000000ull + (uint64_t)ts.tv_nsec;
return 1;
#else
LARGE_INTEGER freq, now;
if (!QueryPerformanceFrequency(&freq) || freq.QuadPart <= 0) return 0;
if (!QueryPerformanceCounter(&now) || now.QuadPart < 0) return 0;
const uint64_t q = (uint64_t)now.QuadPart, f = (uint64_t)freq.QuadPart;
/*
* Seconds and remainder separately. Counter times a billion overflows
* int64 after roughly fifteen minutes of uptime at the usual 10 MHz --
* longer than a CI runner lives, so the obvious one-liner passes here and
* returns nonsense on a machine that has been up since Tuesday.
*/
*out = (q / f) * 1000000000ull + ((q % f) * 1000000000ull) / f;
return 1;
#endif
}

/*
* The previous sample, per thread.
*
* Thread-local for the reason threads.c gives for the plan itself: two BEAM
* calls on two threads sharing one baseline would measure each other's window
* and neither would get a window it could interpret. A thread's first call
* therefore reports unknown, which is what this platform did on every call
* before.
*
* A window shorter than the accounting resolution does NOT replace the
* baseline. Overwriting it on every call is the bug that makes this whole
* mechanism useless: a tight loop of short calls would reset the start of the
* window each time and never accumulate twenty milliseconds, so the estimate
* would be unknown forever on exactly the workload that needs it. The
* baseline is left to age instead.
*/
/*
* The previous sample, per thread.
*
* Thread-local for the reason threads.c gives for the plan itself: two BEAM
* calls on two threads sharing one baseline would measure each other's window
* and neither would get a window it could interpret. A thread's first call
* therefore reports unknown, which is what this platform answered on EVERY
* call before, so nothing here can be worse than it was.
*/
static TLS BeamAvailSample tl_sample;

static int sampled_competitors(int allowed) {
uint64_t sys = 0u, own = 0u, wall = 0u;
if (!read_system_busy_ns(&sys)) return -1;
if (!read_own_cpu_ns(&own)) return -1;
if (!read_wall_ns(&wall)) return -1;
return beam_competitors_from_samples(&tl_sample, sys, own, wall, allowed);
}
#endif /* __APPLE__ || _WIN32 */

/*
* An explicit pin, for reproducibility.
*
Expand Down Expand Up @@ -180,6 +362,14 @@ int beam_available_cores(void) {
if (read_small_file("/proc/loadavg", buf, sizeof buf)) {
nr = beam_parse_nr_running(buf);
}
#elif defined(__APPLE__) || defined(_WIN32)
/*
* No /proc, so no instantaneous runnable count. The sampled estimate is
* second best and says so: it lags, and it reports unknown until a thread
* has a window worth measuring. Unknown is what this platform answered on
* every call before, so nothing here can be worse than it was.
*/
nr = sampled_competitors(allowed);
#endif
return beam_available_from(allowed, nr);
}
93 changes: 89 additions & 4 deletions src/native/internal/beam/avail.h
Original file line number Diff line number Diff line change
Expand Up @@ -38,14 +38,30 @@
* conservative is the cheap direction -- planning too narrow costs about 2x,
* planning too wide cost up to 3814x.
*
* Every parser returns -1 for "could not tell" rather than guessing. -1 then
* means "assume no contention", and the policy's own halving supplies the
* conservative answer. That is also exactly what a machine with no /proc at
* all gets, so the non-Linux fallback is not a special case anywhere.
* Every reader returns -1 for "could not tell" rather than guessing, and -1
* means "assume no contention". It is the one answer that cannot be wrong in
* the expensive direction by more than the ceiling allows: clause 3 of the
* policy is min(available, 8), so an unknown machine is planned at 8 and the
* error is bounded by that, not by the core count. (An earlier version of
* plan.c halved availability instead, and this paragraph used to credit the
* halving with the conservative answer; the halving is gone and the ceiling
* does that work now.)
*
* What the platforms without /proc do. They have no instantaneous runnable
* count, and the load average they DO have is ruled out above. So they
* difference two cumulative CPU-time readings instead -- see
* beam_competitors_from_cpu_time and beam_competitors_from_samples -- which
* measures competitors over a window rather than at an instant. It is second
* best, and the second-best-ness is explicit: it lags, it reports unknown
* until a thread has a window worth measuring, and every failure path lands
* on the same -1 those platforms used to return on every call. It cannot be
* worse than what it replaced; it can only start being right sooner.
*/
#ifndef BEAM_INTERNAL_AVAIL_H
#define BEAM_INTERNAL_AVAIL_H

#include <stdint.h>

/**
* Runnable scheduling entities, from the fourth field of /proc/loadavg
* ("running/total"). -1 when the text cannot be read.
Expand Down Expand Up @@ -89,6 +105,75 @@ int beam_allowed_cores(void);
*/
int beam_available_from(int allowed, int nr_running);

/**
* Minimum window worth measuring, in nanoseconds. CPU time is accounted in
* ticks of roughly 10 ms on both platforms that need the sampled estimate, so
* a shorter window carries no information: the deltas are zero or one tick
* and the quotient is noise.
*/
#define BEAM_AVAIL_MIN_WINDOW_NS 20000000u

/**
* Competitors implied by two cumulative CPU-time samples, in the units
* `beam_available_from` takes: runnable entities including the caller. -1 when
* the window is too short to mean anything.
*
* This is how a machine with no /proc answers the question Linux answers with
* the runnable count. The quantity is competitors, NOT total load, which is
* why `own_ns` is subtracted: a window spanning BEAM's own eight-thread region
* reads as eight cores busy, and counting that as contention would narrow the
* next call BECAUSE OF THE PREVIOUS ONE -- the feedback loop this file rejects
* the load average for. Linux escapes it for free, the runnable count being
* instantaneous: by the time it reads, BEAM's workers have exited.
*
* Both reads are averages over the window rather than instants, so this signal
* lags where the runnable count does not. The lag is bounded and lands on the
* safe side: a machine that was busy and is now idle plans narrow, costing
* about 2x, while the error in the other direction cost up to 3814x. A
* fraction of a core therefore rounds UP, and a sample whose own time exceeds
* the system total -- the two clocks are not read atomically -- reports no
* competition rather than negative competition.
*
* Pure, so the arithmetic is tested directly; the platform readers that
* produce the samples are the only part a test cannot pin to an exact answer.
*/
int beam_competitors_from_cpu_time(uint64_t sys_busy_ns, uint64_t own_ns,
uint64_t wall_ns, int allowed);

/**
* One thread's previous CPU-time sample. Exposed so that the sample-to-sample
* step below can be driven from a test rather than from two clocks.
*/
typedef struct {
uint64_t sys; /**< Busy CPU nanoseconds across every CPU. */
uint64_t own; /**< This process's CPU nanoseconds. */
uint64_t wall; /**< Monotonic nanoseconds. */
int have; /**< Zero until the first reading is stored. */
} BeamAvailSample;

/**
* The estimate from a new reading and the previous sample, updating the sample
* in place. -1 when the pair cannot be interpreted yet.
*
* Pure apart from `*prev`, which is the whole point: the three rules that make
* the sampled estimate work are here rather than in platform code, so a test
* can pin them on any machine.
*
* 1. A thread's FIRST reading becomes the baseline and reports unknown.
* There is nothing to difference against.
* 2. A window below `BEAM_AVAIL_MIN_WINDOW_NS` reports unknown and LEAVES
* THE BASELINE ALONE, so it keeps ageing. Replacing it on every call is
* the bug that would make the mechanism useless: a tight loop of short
* calls would restart the window each time and never reach twenty
* milliseconds, so the estimate would stay unknown on exactly the
* workload that needs it.
* 3. A reading that moves backwards in any of the three series -- which the
* clocks promise not to do, and which a test must still pin -- resets the
* baseline and reports unknown rather than subtracting into an underflow.
*/
int beam_competitors_from_samples(BeamAvailSample *prev, uint64_t sys,
uint64_t own, uint64_t wall, int allowed);

/**
* The estimate the policy is given: free cores right now, at least one.
*
Expand Down
Loading
Loading