pagefun — Apply matrix operators page-by-page across higher-dimensional arrays.
pagefun(func, A, B, ...) applies supported operators independently across pages indexed by third-and-higher dimensions, following MATLAB-compatible pagewise execution semantics.
Syntax
Y = pagefun(func, A, B)
Y = pagefun(func, A1, An...)Inputs
func- Type
Any- Required
- Yes
- Description
- Operator/function handle (currently `@mtimes`).
A- Type
Any- Required
- Yes
- Description
- First paged input array.
B- Type
Any- Required
- Yes
- Description
- Second paged input array.
func- Type
Any- Required
- Yes
- Description
- Operator/function handle.
A1- Type
Any- Required
- Yes
- Description
- First paged input array.
An- Type
Any- Required
- Variadic
- Description
- Additional paged input arrays.
Returns
Y- Type
Any- Description
- Result of applying the operator page-by-page.
Errors
RunMat:pagefun:TooManyOutputs- When
- More than one output is requested.
- Message
pagefun: expected at most one output
RunMat:pagefun:InvalidCallable- When
- Function selector is not a supported pagefun operator handle.
- Message
pagefun: invalid function selector
RunMat:pagefun:UnsupportedOperation- When
- Operator is not implemented by pagefun.
- Message
pagefun: unsupported operation
Behavior
MATLAB-compatible calls require a function handle. In runmat compatibility mode, builtin names supplied as character vectors or string scalars are accepted as a RunMat extension.
The first two dimensions of each input form the matrix operated on by the builtin. Dimensions three and up identify individual pages. Inputs with fewer pages are broadcast so long as the page extent is 1.
Any combination of empty matrices and empty page extents produces empty results with MATLAB-compatible shapes.
MATLAB-compatible calls require at least one distributed or gpuArray input. In runmat compatibility mode, all-host operands are accepted as a RunMat extension and return host results.
When any operand is a gpuArray, provider fallback gathers inputs through the provider that owns them and restores supported results to that same provider. Automatic residency remains transparent, while an explicit gpuArray remains resident whenever its class can be represented by the owner.
Integer operands inherit the selected function's contract. For @mtimes, one operand must be scalar when either operand is an integer class; each page uses exact native integer storage, applies the class-preserving saturation rules of mtimes, and never passes through a floating copy.
GPU residency
WGPU provider accelerates batched @mtimes; if no provider hook is present the runtime evaluates on the host and re-uploads numeric results.
RunMat Accelerate exposes a custom pagefun provider hook. When every operand is a floating gpuArray and the owning provider implements the operation (the WGPU backend does for @mtimes), pages stay on the device and execute via a tiled compute shader. Mixed host/GPU inputs, integer pages, and unsupported provider operations use owner-aware host fallback; exact native storage is retained and supported outputs are restored to the original provider.
No. RunMat's auto-offload planner migrates tensors to the GPU when beneficial. When you explicitly pass any gpuArray input, pagefun returns supported real or complex numeric results on the device whenever the provider can accept the upload.
Additional usage
Batched matrix multiplication across pages
A = reshape(1:12, [2 2 3]);
B = reshape(13:24, [2 2 3]);
C = pagefun(@mtimes, A, B)
Expected display: C(:,:,1) =
55 63
82 94
C(:,:,2) =
211 235
246 274
C(:,:,3) =
431 471
474 518
Broadcasting a single page against multiple pages
A = reshape(1:8, [2 2 2]);
B = eye(2);
C = pagefun(@mtimes, A, B); % B broadcasts across the page dimension
Working with gpuArray inputs
G1 = gpuArray(rand(4, 4, 8));
G2 = gpuArray(rand(4, 4, 8));
H = pagefun(@mtimes, G1, G2);
firstPage = gather(H(:, :, 1)); % Inspect the first product page on the host
Handling empty page dimensions
Z = zeros(2, 2, 0);
R = pagefun(@mtimes, Z, Z);
size(R)
Expected display: ans =
2 2 0
Execution boundaries
Only the matrix-product operation is supported; arbitrary closures, user overrides and bound receivers are not executed. Unknown selectors can fail but do not introduce unknown callback effects.
Numeric arrays are the complete input and output surface. Nested cells, structures, foreign values and distributed arrays are rejected before provider work, so there are no nested resident outputs. Direct distributed input is unsupported; ordinary worker calls require their own provider ownership and the shared runtime kernel.
Native/JIT/AOT and browser execution use the portable typed runtime kernel. Workload features are matrix extents, page broadcast extents, classes, complexity, requested output count and resident transfer requirements. Shared placement services own timing, scheduling and feedback; no per-builtin thresholds are used.
Provider outputs must match owner, device, shape, precision, real storage and class and must not alias inputs. Invalid outputs are released without freeing borrowed inputs. Only typed unsupported-operation failures allow host fallback; other provider failures remain visible.
The single result may be discarded, but admission, shape checks and computation still occur. More than one output is rejected before provider access.
Documentation reconciliation
Legacy signatures, summary, description, behavior, examples, FAQs, source and links are preserved or corrected here. Fusion flags and f32/f64 provider support are canonical placement/operation facts; no feature is required. Old display text is explanatory, not a numerical test oracle.
Examples
batch
A = reshape(1:8,[2 2 2]); B = eye(2); C = pagefun(@mtimes,A,B);empty
Z = zeros(2,2,0); R = pagefun(@mtimes,Z,Z);integer
A = intmax('uint64'); R = pagefun(@mtimes,A,uint64(1));resident
A = single(reshape(1:8,[2 2 2])); G = gpuArray(A); I = gpuArray(single(eye(2))); H = pagefun(@mtimes,G,I); C = gather(H);Using pagefun with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how pagefun changes the result.
Run a small pagefun example, explain the result, then change one input and compare the output.
FAQ
Which functions does pagefun support today?⌄
RunMat currently supports @mtimes page-wise. Additional MATLAB page-aware functions will be added over time as the GPU provider hooks land.
How are page dimensions inferred?⌄
The first two dimensions represent the matrix operated on by the builtin. Any remaining dimensions are treated as page indices. Inputs with fewer trailing dimensions receive implicit singleton expansion to match other operands.
What happens if the pages are incompatible?⌄
pagefun raises a MATLAB-compatible error describing the mismatched page dimension. Matrix dimension mismatches are forwarded from the underlying builtin (for example, Inner matrix dimensions must agree for @mtimes).
Are results always uploaded back to the GPU?⌄
When any operand is a gpuArray and an acceleration provider is registered, supported uniform real or complex numeric results are uploaded back to the device. An all-host RunMat-extension call returns a host result.
Does pagefun participate in fusion?⌄
No. Because pagefun performs independent page products it forms a fusion barrier. Upstream expressions are evaluated before entering pagefun.
Related Acceleration functions
Source you can read
Every RunMat function's source is public. Read exactly how pagefun is executed, line by line, in Rust.
- View the source for pagefun in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.