Add opt-in tensor spill to disk for colocated datasets

[dsaini2-sc]

Adds an opt-in tensor-spill layer to gigl/utils/share_memory.py, plus its tests. Off by default: with GIGL_TENSOR_SPILL_DIR unset, nothing changes.

Why

In colocated mode each rank's features and topology live in POSIX shared memory. /dev/shm is tmpfs, i.e. RAM, and without swap those pages cannot be evicted; worse, share_memory_() on an anonymous tensor copies it into /dev/shm, so the largest tensors transiently exist twice -- GLT's Graph.__init__ shares the CSR unconditionally, and at billion-node scale that transient 2x is what OOM-kills the graph build. Spilling large tensors to a local disk turns their bytes into reclaimable page cache, letting large graphs run colocated without a separate storage tier.

What it adds

• prepare_spill_dir() -- run-start cleanup of the spill directory. Cleanup never runs at exit, because the process that spills exits before the consumers unmap; a spill directory belongs to one workload and is reused across its sequential runs.
• spill_tensor_to_disk / allocate_disk_backed / allocate_preshared -- placement. None always means "fall back to memory". Sequential-write destinations go to disk (~3.1x measured write cost, bytes never anonymous); scattered destinations prefer memory, because an uncached 8-byte file write is a 4 KiB read-modify-write and a CSR build revisits the same pages hundreds of times. Block reservation via posix_fallocate is mandatory, so a filesystem that fills or cannot reserve fails as OSError at allocation, never as SIGBUS on a later page write.
• SpilledTensorHandle + share_memory_for_ipc / resolve_spilled_handles -- crossing process boundaries by descriptor. Pickling an mmap-backed tensor copies every byte back into /dev/shm, silently undoing the spill, so handles travel instead.
• release_page_cache / release_page_cache_by_path -- release the cgroup charge of written-once data (msync, then MADV_DONTNEED, then FADV_DONTNEED; skipping the middle step makes the call a silent no-op).
• Introspection: is_tensor_spilling_enabled, is_disk_backed, disk_backed_handle, has_live_mapping.

Placement decisions read available_memory_bytes() from #756.

Behaviour change

None when spilling is unset. share_memory() keeps its -> None signature; its one change is leaving an already disk-backed tensor alone rather than copying it into /dev/shm, reachable only with spilling on.

Testing

32 tests pass; ty and ruff clean. The tests exercise the real filesystem: spill/re-map round trips, threshold and dtype refusals, handle pickling across processes, forced posix_fallocate refusal (both "no space" and "not supported") asserting memory fallback with no leftover file, preshared allocation asserted on data_ptr stability across share_memory_(), and page-cache release asserted on measured page residency (mincore) rather than return values.

Open questions

• Module home: this extends share_memory.py because share_memory() itself must recognise disk-backed tensors; a separate module importing the registry check is workable if a ~1k-line utility file is unwanted.
• Env vars vs config plumbing: env vars are required at the mp.spawn boundary, but a config field mapped to them may be the friendlier surface.
• Defaults: the 2 GiB spill threshold and 16 GiB scattered-write reserve are the values validated at ~1B-node scale.
• Should the final direct-to-shared-memory allocation also require cgroup headroom, failing fast instead of risking a later OOM?

[kmontemayor2-sc]

Nice work Deepak! Thanks :)

Did we consider torch.from_file? See https://github.com/Snapchat/GiGL/pull/757/changes#r3814543741. I think that if that's feasible (and in my testing it seems like it should be, without adding additional mem overhead), then we should be able to simplify this a lot by using that API and not needing the registry or new dataclasses / handles / etc?

[kmontemayor2-sc]

Thanks for the interations here!