pl.prefetch

Asynchronous GM to L2 prefetch. The handle types these produce are described in the feature matrix.

pl.prefetch.* — asynchronous GM->L2 prefetch operations.

A latency-hiding cache hint: async_prefetch starts an SDMA-backed pull of a global-memory region into L2 while unrelated compute proceeds, and wait blocks until it lands. The prefetch changes no tensor values, so a kernel is numerically identical with or without it — only performance differs.

Typical usage::

ctx = pl.prefetch.make_context()
evt = pl.prefetch.async_prefetch(x, ctx)
session = pl.prefetch.session(ctx)
...                                            # unrelated compute overlaps
pl.prefetch.wait(evt, session)                 # x is now resident in L2

The runtime owns and injects the SDMA scratch workspace. One-shot execution enables SDMA automatically from generated artifact metadata; an explicitly reused worker must be created with ChipWorker(enable_sdma=True). The current runtime-provisioned path is covered on onboard a2a3. A runtime without an SDMA provider fails during worker initialization; there is no fallback or no-op path.

async_prefetch(src, ctx)

Start one asynchronous prefetch of a GM region into L2 cache.

Does not block and does not modify src.

Parameters:

Name	Type	Description	Default
src	Tensor	A flat contiguous logical-1D GM pl.Tensor to pull into L2. The op verifier (C++) requires a fully static shape whose dimensions are all 1 except the last — e.g. [N] or [1, N].	required
ctx	PrefetchAsyncContext	A PrefetchAsyncContext from make_context.	required

Returns:

Type	Description
AsyncEvent	An AsyncEvent to pass to wait along
AsyncEvent	with the session.

make_context()

Build an asynchronous-prefetch context with a runtime-injected workspace.

The caller supplies no workspace. Codegen and the runtime bind the returned context to a hidden runtime-owned SDMA allocation.

Returns:

Type	Description
PrefetchAsyncContext	A PrefetchAsyncContext handle to pass to
PrefetchAsyncContext	async_prefetch
PrefetchAsyncContext	and session.

session(ctx)

Project the asynchronous session bound to a prefetch context.

Parameters:

Name	Type	Description	Default
ctx	PrefetchAsyncContext	A PrefetchAsyncContext from make_context.	required

Returns:

Type	Description
AsyncSession	An AsyncSession to pass to wait.

wait(event, session_handle)

Wait for an asynchronous prefetch event to complete within its session.

Call this before the hot loop that consumes the prefetched region so the data is resident in L2.

Parameters:

Name	Type	Description	Default
event	AsyncEvent	An AsyncEvent from async_prefetch.	required
session_handle	AsyncSession	The matching AsyncSession from session.	required

Returns:

Type	Description
Scalar	A BOOL Scalar done flag.