aether_dsc

aether-dsc — the sealed AETHER header payload.

aether ships to Python-only users as a SEALED PAYLOAD, never as readable headers inside a wheel’s include tree: one digest-named, zlib-compressed tar blob (opacity, not secrecy — see aether_dsc._core) carrying the aether//rtc/ headers a HAWK-emitted device kernel needs, plus eagle’s plugin/gref_layout.h (device-clean) and plugin/gref_abi.h (host-only — NVRTC never sees its real bytes; hawk.compile.nvrtc serves an alias to the layout header’s instead). Two consumers:

• device — NVRTC compiles a kernel straight from payload()’s in-memory headers mapping; nothing touches disk.

• host, or any file-only compiler — Payload.serve() materialises the payload into a private, owner-only RAM directory for the compile’s lifetime and removes it afterwards, failure path included.

Typical use:

import aether_dsc
p = aether_dsc.payload()        # the blob shipped in this wheel
# device: hand p.digest / p.headers to NVRTC (hawk.compile.nvrtc)
with p.serve() as include_root:  # host / any file compiler
    ...                          # -I include_root

Building a payload from a live checkout (never the shipped-wheel path — a developer’s own aether tree, or the CLI that regenerates the shipped blob) goes through seal(); see aether_dsc.seal’s module docstring.

Module Attributes

version

This distribution's version — tracks aether's own (aether/version.h: constexpr version()), because a sealed payload speaks for exactly one aether checkout and a version skew between the two would silently claim otherwise.

Functions

payload()

The sealed blob shipped in this distribution — decompressed once per process and cached; every call after the first returns the same object.

class aether_dsc.Payload(digest, headers, host_only_names=frozenset({}))

Bases: object

A sealed set of headers plus its content digest.

headers maps include-relative names (aether/…, rtc/<std name>, plugin/gref_layout.h) to their bytes; digest is digest_of() applied to that mapping — two Payload instances with the same file set and content always carry the same digest, independent of how or in what order their files were discovered (aether_dsc.seal’s own order-independence guarantee, exercised by tests/test_aether_dsc.py::test_seal_digest_order_independent).

host_only_names names the subset of headers that is the HOST-ONLY section: sealed (so serve() writes them out for a host -I root exactly like every other entry) but never claimed NVRTC-clean and never handed to an NVRTC compile — see device_headers. digest covers headers whole, host-only entries included, so a changed host-only file changes the digest too (the cache-validity term every compile keys on).

Parameters:

• digest (str)

• headers (Mapping[str, bytes])

• host_only_names (frozenset[str])

digest

headers

host_only_names

property device_headers: dict[str, bytes]

headers minus the host-only section — what an NVRTC compile is actually served (hawk.compile.drivers’s device path, hawk.compile.nvrtc’s public device/cubin): the host-only headers are never NVRTC-clean-checked and must never reach NVRTC even as an unreferenced, served-but-unused file.

serve()

Materialise every header into a PRIVATE, owner-only directory for the compile’s lifetime, then remove it — on the normal exit path and when the with block raises.

Prefers a tmpfs (/dev/shm, checked via /proc/mounts — never assumed from the path alone) so nothing touches spinning or networked storage; falls back to $TMPDIR otherwise. A private mount namespace with its own tmpfs is an opportunistic upgrade this function does not attempt: measurement found it refused outright on an SELinux-enforcing box, so the plain RAM directory is the one path every caller can rely on.

Return type:

Iterator[Path]

aether_dsc.payload()

The sealed blob shipped in this distribution — decompressed once per process and cached; every call after the first returns the same object.

Raises FileNotFoundError when this checkout carries no blob yet (a source tree that has never run python -m aether_dsc.seal, or an editable install before the first seal). Nothing here falls back to sealing the live tree — that fallback belongs to hawk.compile.payload.current_payload(), gated on $HAWK_AETHER_INCLUDE: a caller that wants “seal if there is no blob” asks for it explicitly, payload() never guesses.

Return type:

Payload

aether_dsc.version = '0.2.2'

This distribution’s version — tracks aether’s own (aether/version.h: constexpr version()), because a sealed payload speaks for exactly one aether checkout and a version skew between the two would silently claim otherwise.