Clarify and publish the host-reference interface

Author: maleadt

src/interface.jl

@@ -429,19 +429,43 @@ the check-and-compile sequence (all back-ends already do, e.g. `mtlfunction_lock
 """
 function cached_results end
 
-# Host-reference metadata belongs to the compiler pipeline rather than a particular result
-# cache. Julia 1.10 keeps results in a process-local cache, while newer Julias can persist
-# them in package images, but both versions need the same representation while compiling.
+"""
+    JuliaValueRef(value)
+
+A Julia value used as the serializable identity of a host reference. Resolve it in the active
+session with [`resolve_host_reference`](@ref); a loader that writes the resulting address into
+device storage must keep `value` rooted for as long as that storage remains reachable.
+"""
 struct JuliaValueRef
     value::Any
 end
 
-struct RuntimeGlobalRef
-    name::Symbol
+"""
+    CGlobalRef(symbol)
+
+A libjulia C data global. Resolving this reference calls `jl_cglobal` for `symbol` and loads
+the word stored at that address.
+"""
+struct CGlobalRef
+    symbol::Symbol
 end
 
-const HostReference = Union{JuliaValueRef,RuntimeGlobalRef}
+"""
+    HostReference
 
+A serializable source for a host-derived word: either a [`JuliaValueRef`](@ref) or a
+[`CGlobalRef`](@ref).
+"""
+const HostReference = Union{JuliaValueRef,CGlobalRef}
+
+"""
+    HostReferences(slots, embedded_pointer)
+
+Host-reference metadata accompanying a module. `slots` maps each object-code symbol to the
+source of the word that must be written there. `embedded_pointer` conservatively records that
+an unavoidable session pointer has been embedded, so the artifact cannot be serialized into a
+package image even if `slots` is empty.
+"""
 mutable struct HostReferences
     slots::Dict{String,HostReference}
     embedded_pointer::Bool
@@ -452,13 +476,19 @@ copy_host_references(refs::HostReferences) =
     HostReferences(copy(refs.slots), refs.embedded_pointer)
 
 same_host_reference(a::JuliaValueRef, b::JuliaValueRef) = a.value === b.value
-same_host_reference(a::RuntimeGlobalRef, b::RuntimeGlobalRef) = a.name === b.name
+same_host_reference(a::CGlobalRef, b::CGlobalRef) = a.symbol === b.symbol
 same_host_reference(::HostReference, ::HostReference) = false
 
+"""
+    resolve_host_reference(ref) -> UInt
+
+Resolve `ref` to its current-session word. Loader-based backends use this after loading the
+object and before exposing a callable function.
+"""
 resolve_host_reference(ref::JuliaValueRef) =
     UInt(ccall(:jl_value_ptr, Ptr{Cvoid}, (Any,), ref.value))
-function resolve_host_reference(ref::RuntimeGlobalRef)
-    address = ccall(:jl_cglobal, Any, (Any, Any), String(ref.name), UInt)
+function resolve_host_reference(ref::CGlobalRef)
+    address = ccall(:jl_cglobal, Any, (Any, Any), String(ref.symbol), UInt)
     return unsafe_load(address)
 end
 
@@ -467,8 +497,8 @@ end
 
 Lower compiler-managed Julia value globals and Julia runtime globals for `job`'s final
 backend representation. The default lowering resolves every live reference in the current
-Julia session. Backends with a loader relocation mechanism may leave word-sized slots for
-their loader instead.
+Julia session. Backends with a loader relocation mechanism may call
+[`emit_host_reference_slots!`](@ref) instead, then resolve and patch those slots after loading.
 """
 function lower_host_references!(@nospecialize(job::CompilerJob), mod::LLVM.Module,
                                 refs::HostReferences)
@@ -596,6 +626,8 @@ end
 end # HAS_INTEGRATED_CACHE
 
 @public GPUCompilerCacheToken, cache_owner, cached_results
+@public JuliaValueRef, CGlobalRef, HostReference, HostReferences
+@public lower_host_references!, emit_host_reference_slots!, resolve_host_reference
 
 # the method table to use
 #

src/jlgen.jl

@@ -834,6 +834,12 @@ function resolve_host_reference_slots!(mod::LLVM.Module, refs::HostReferences)
     return
 end
 
+"""
+    emit_host_reference_slots!(mod, refs)
+
+Prepare the globals named by `refs.slots` for loader-based lowering. Each remains a writable,
+word-sized external symbol that the loader must resolve and patch after loading the object.
+"""
 function emit_host_reference_slots!(mod::LLVM.Module, refs::HostReferences)
     check_host_reference_slots!(mod, refs)
     mod_gvs = globals(mod)

src/mcgen.jl

@@ -57,7 +57,7 @@ function (self::CollectRuntimeGlobalReferences)(mod::LLVM.Module)
                     actual_name = LLVM.name(slot)
                     haskey(self.refs.slots, actual_name) &&
                         error("Duplicate Julia runtime global slot '$actual_name'")
-                    self.refs.slots[actual_name] = RuntimeGlobalRef(Symbol(fn))
+                    self.refs.slots[actual_name] = CGlobalRef(Symbol(fn))
                 end
                 slot
             end

test/native.jl

@@ -765,7 +765,7 @@ end
         refs = GPUCompiler.HostReferences()
         @test GPUCompiler.collect_runtime_global_references!(job, mod, refs)
         name = only(keys(refs.slots))
-        @test refs.slots[name] == GPUCompiler.RuntimeGlobalRef(:jl_float32_type)
+        @test refs.slots[name] == GPUCompiler.CGlobalRef(:jl_float32_type)
         @test occursin("externally_initialized global i64 0", string(mod))
 
         mod = parse(LLVM.Module, """
@@ -778,7 +778,7 @@ end
         refs = GPUCompiler.HostReferences()
         @test GPUCompiler.collect_runtime_global_references!(job, mod, refs)
         name = only(keys(refs.slots))
-        @test refs.slots[name] == GPUCompiler.RuntimeGlobalRef(:jl_float32_type)
+        @test refs.slots[name] == GPUCompiler.CGlobalRef(:jl_float32_type)
         @test occursin("externally_initialized global i64 0", string(mod))
     end
 end