gigl.scripts.glt_wheel_cache#

Pure helpers for the per-machine cache of built GraphLearn-Torch wheels.

Standard library only: this runs from post_install.py during environment setup, before the rest of the repo’s dependencies are necessarily importable.

Attributes#

GLT_COMMIT

Functions#

`cache_entry_lock`(cache_entry)	Holds an exclusive cross-process lock for one cache entry.
`compute_cache_key`(commit, patch_contents, ...)	Names the cache entry for the wheel built from the given inputs.
`describe_wheel`(wheel)	Describes a wheel by path, size and sha256 for the install log.
`find_cached_wheel`(cache_entry)	Finds the wheel in a cache entry.
`publish_wheel`(wheel, cache_entry)	Publishes a wheel as a cache entry, replacing any existing entry.
`read_patches`(patches_dir)	Reads every `*.patch` file in a directory.

Module Contents#

gigl.scripts.glt_wheel_cache.cache_entry_lock(cache_entry)[source]#

Holds an exclusive cross-process lock for one cache entry.

Blocks until any other holder releases it. The lock file sits next to the entry, not inside it, so evicting or replacing the entry does not delete the lock.

Example

>>> with cache_entry_lock(Path("/tmp/cache/glt-key")):
...     wheel = find_cached_wheel(Path("/tmp/cache/glt-key"))

Parameters:: cache_entry (pathlib.Path) – The cache entry directory the lock guards; it may not exist.
Yields:: None, while the lock is held.
Return type:: collections.abc.Iterator[None]

gigl.scripts.glt_wheel_cache.compute_cache_key(commit, patch_contents, build_script, variant, torch_version, python_tag, platform_tag)[source]#

Names the cache entry for the wheel built from the given inputs.

Every input that changes the built wheel is part of the name.

The p segment is a hash of the build script followed by the patches. Each item is length-prefixed before hashing, so the boundaries between items are part of the digest.

Example

>>> compute_cache_key(
...     GLT_COMMIT, [b"patch"], b"#!/bin/bash", "cpu", "2.8.0", "cp311", "linux-x86_64"
... )
'glt-88ff111a-p2e56eb6940b0-cpu-torch2.8.0-cp311-linux-x86_64'

Parameters:

commit (str) – Pinned upstream GLT commit sha; its first 8 characters are used.
patch_contents (collections.abc.Sequence[bytes]) – Contents of the local patches, hashed in the order given.
build_script (bytes) – Contents of install_glt.sh.
variant (str) – Build variant, e.g. cpu or cuda7.5.
torch_version (str) – Torch version the wheel links against, e.g. 2.8.0+cu128.
python_tag (str) – Python ABI tag, e.g. cp311.
platform_tag (str) – Platform the wheel is built for, sysconfig.get_platform(), e.g. linux-x86_64.

Returns:

The cache entry name, glt-<commit8>-p<build script and patches hash>-<variant> followed by -torch<version>-<python tag>-<platform tag>.

Return type:

str

gigl.scripts.glt_wheel_cache.describe_wheel(wheel)[source]#

Describes a wheel by path, size and sha256 for the install log.

Every hit, miss and publish logs this line, so a tampered or corrupt artifact can be traced to the exact bytes that were installed.

Example

>>> describe_wheel(Path("/tmp/glt-0.whl"))
'/tmp/glt-0.whl (size=5 bytes, sha256=...)'

Parameters:: wheel (pathlib.Path) – Path of the wheel file.
Returns:: <path> (size=<bytes> bytes, sha256=<hex digest>).
Return type:: str

gigl.scripts.glt_wheel_cache.find_cached_wheel(cache_entry)[source]#

Finds the wheel in a cache entry.

Example

>>> find_cached_wheel(Path("/tmp/cache/glt-key"))
PosixPath('/tmp/cache/glt-key/graphlearn_torch-0.2-cp311-linux_x86_64.whl')

Parameters:: cache_entry (pathlib.Path) – The cache entry directory; it may not exist.
Returns:: The wheel path, or None if there is none. An entry holds exactly one wheel; if it somehow holds several, the first by filename is returned.
Return type:: pathlib.Path | None

gigl.scripts.glt_wheel_cache.publish_wheel(wheel, cache_entry)[source]#

Publishes a wheel as a cache entry, replacing any existing entry.

The entry is assembled in a temp dir inside the cache root and renamed into place, so a concurrent run never sees a half-written entry.

The caller must hold cache_entry_lock(cache_entry); otherwise replacing the entry can delete a wheel another process just published.

Example

>>> entry = Path("/tmp/cache/glt-key")
>>> with cache_entry_lock(entry):
...     publish_wheel(Path("/tmp/build/glt.whl"), entry)
PosixPath('/tmp/cache/glt-key/glt.whl')

Parameters:

wheel (pathlib.Path) – The built wheel to publish.
cache_entry (pathlib.Path) – Destination entry directory, <cache root>/<cache key>.

Returns:

The path of the wheel inside the cache entry.

Return type:

pathlib.Path

gigl.scripts.glt_wheel_cache.read_patches(patches_dir)[source]#

Reads every *.patch file in a directory.

Example

>>> read_patches(Path("/tmp/patches"))
[b'<contents of 0001-first.patch>', b'<contents of 0002-second.patch>']

Parameters:: patches_dir (pathlib.Path) – Directory containing the patch files.
Returns:: The file contents, sorted by filename (the order the patches are applied in).
Raises:: FileNotFoundError – If the directory has no *.patch files, e.g. they were left out of the installed package; hashing an empty set would give a cache key that ignores the patches.
Return type:: list[bytes]

gigl.scripts.glt_wheel_cache.GLT_COMMIT: Final = '88ff111ac0d9e45c6c9d2d18cfc5883dca07e9f9'[source]#