# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Advanced Micro Devices, Inc. All rights reserved.
"""
Gluon device side of triggered plans (see ``iris.experimental.plan``).
Same handle and gate layout as ``iris.experimental.plan.triton``; only the kernel language differs.
"""
from triton.experimental import gluon
from triton.experimental.gluon import language as gl
from triton.language.core import _aggregate as aggregate
from iris.experimental.plan.triton import (
H_GATES,
H_NUM_CHUNKS,
H_NUM_GROUPS,
H_RANK,
H_ROUND,
H_WORLD_SIZE,
HEADER_WORDS,
R_ARRIVAL,
R_EXPECTED,
R_OWNER,
RECORD_WORDS,
)
from iris.mem.utils import wait_cnt
@gluon.jit
def _peek(ptr):
"""
A system-scope load for polling. Unlike an acquire atomic it does not serialize with the copy engines' or
other programs' atomics on the same word, but each wave issues its own, so waves can see different values:
poll with it, then confirm with the CTA-uniform acquire check.
"""
return gl.load(ptr, volatile=True, cache_modifier=".cv")
@gluon.jit
def _group_word(num_chunks, world_size, group):
"""Gate word of ``group``'s arrival, as ``triggered.group_gate`` computes it on the host."""
return 2 * num_chunks + 2 * world_size + 2 + group
[docs]
@aggregate
class TriggeredView:
"""
Gluon device handle for one round of a triggered plan.
Usage::
@gluon.jit
def producer(out, handle, ...):
cv = TriggeredView.initialize(handle)
... # write this program's part of chunk c
cv.mark_ready(c) # whole CTA, after its writes
@gluon.jit
def consumer(out, handle, ...):
cv = TriggeredView.initialize(handle)
cv.wait(c) # chunk c's data is now visible
x = gl.load(out + ...)
"""
view: gl.tensor
gates: gl.tensor
round: gl.tensor
rank: gl.tensor
num_chunks: gl.tensor
@gluon.constexpr_function
def __init__(self, view, gates, round, rank, num_chunks):
self.view = view
self.gates = gates
self.round = round
self.rank = rank
self.num_chunks = num_chunks
[docs]
@staticmethod
@gluon.jit
def initialize(handle):
"""Read the plan's handle tensor (from ``TriggeredPlan.start()``)."""
gates = gl.cast(gl.load(handle + H_GATES), gl.pointer_type(gl.int32))
return TriggeredView(
handle, gates, gl.load(handle + H_ROUND), gl.load(handle + H_RANK), gl.load(handle + H_NUM_CHUNKS)
)
@gluon.jit
def _record(self, chunk, word):
return gl.load(self.view + HEADER_WORDS + chunk * RECORD_WORDS + word)
[docs]
@gluon.jit
def owns(self, chunk):
"""True if this rank produces chunk ``chunk``."""
return self._record(chunk, R_OWNER) == self.rank
[docs]
@gluon.jit
def mark_ready(self, chunk):
"""
Declare this CTA's writes to chunk ``chunk`` done; the chunk is sent once all of its writers have.
Call from the whole CTA, after the CTA's writes to the chunk: outside divergent branches and
outside ``gl.warp_specialize`` partitions.
"""
# Copy engines read behind L2: every wave's stores must land before the release writes back
wait_cnt()
gl.barrier()
# Each writer's release writes back its own L2 before its increment, so the increment that
# reaches writers * round follows every writer's data
gl.atomic_add(self.gates + chunk, 1, sem="release", scope="sys")
[docs]
@gluon.jit
def arrived(self, chunk):
"""
True once chunk ``chunk`` is visible here this round: for this rank's own chunks, once marked
ready; for another rank's chunk in a group, once the whole group has arrived here. Always
true of chunks not sent to this rank.
Call uniformly across the CTA: the result reaches the other waves through a CTA barrier, so
every wave must make the same number of calls (true of the other waits too).
"""
word = self._record(chunk, R_ARRIVAL)
target = self._record(chunk, R_EXPECTED) * self.round
return gl.atomic_add(self.gates + word, 0, sem="acquire", scope="sys") >= target
[docs]
@gluon.jit
def wait(self, chunk):
"""
Spin until ``arrived(chunk)``. Each wave first polls with its own loads, which do not serialize with
the copy engines' atomics on the word; the acquire check that follows is CTA-uniform.
"""
word = self.gates + self._record(chunk, R_ARRIVAL)
target = self._record(chunk, R_EXPECTED) * self.round
while _peek(word) < target:
pass
while self.arrived(chunk) == 0:
pass
@gluon.jit
def _sends_to(self, peer):
"""True if this rank's chains go to rank ``peer``, so its completion counter counts rounds."""
return gl.load(self.view + HEADER_WORDS + self.num_chunks * RECORD_WORDS + peer) != 0
[docs]
@gluon.jit
def group_arrived(self, group):
"""
True once every chunk of ``group`` sent to this rank has arrived this round. Always true of a
group with no chunks sent here, including a group no chunk uses (a debug build asserts on
that, since it is likely a typo).
"""
world_size = gl.load(self.view + H_WORLD_SIZE)
known = (group >= 0) & (group < gl.load(self.view + H_NUM_GROUPS))
gl.device_assert(known, "wait_group: no chunk uses this group")
expected = gl.load(
self.view + HEADER_WORDS + self.num_chunks * RECORD_WORDS + world_size + group, mask=known, other=0
)
word = self.gates + _group_word(self.num_chunks, world_size, group)
seen = gl.atomic_add(word, 0, mask=known, sem="acquire", scope="sys")
return (known == 0) | (seen >= expected * self.round)
[docs]
@gluon.jit
def wait_group(self, group):
"""Spin until ``group_arrived(group)``, polling each wave's own loads first (see ``wait``)."""
world_size = gl.load(self.view + H_WORLD_SIZE)
known = (group >= 0) & (group < gl.load(self.view + H_NUM_GROUPS))
if known:
expected = gl.load(self.view + HEADER_WORDS + self.num_chunks * RECORD_WORDS + world_size + group)
word = self.gates + _group_word(self.num_chunks, world_size, group)
while _peek(word) < expected * self.round:
pass
while self.group_arrived(group) == 0:
pass
[docs]
@gluon.jit
def sent(self):
"""True once every peer has received this rank's chunks this round, so they may be overwritten."""
pending = 0
for peer in range(gl.load(self.view + H_WORLD_SIZE)):
if self._sends_to(peer):
completion = self.gates + 2 * self.num_chunks + peer
pending += (gl.atomic_add(completion, 0, sem="acquire", scope="sys") < self.round).to(gl.int32)
return pending == 0
[docs]
@gluon.jit
def wait_sent(self):
"""Spin until ``sent()``, polling each wave's own loads first (see ``wait``)."""
for peer in range(gl.load(self.view + H_WORLD_SIZE)):
if self._sends_to(peer):
while _peek(self.gates + 2 * self.num_chunks + peer) < self.round:
pass
while self.sent() == 0:
pass