Documentation
¶
Overview ¶
Package runtimecell builds and resolves packed extension runtime cells.
Index ¶
- func ArtifactIdentity(entryDir string) (string, bool)
- func CurrentGoPackedCellEntry(cacheRoot, key string, extensions []GoExtension) (string, bool, error)
- func CurrentPythonPackedCellEntry(cacheRoot, key string, extensions []PythonExtension) (string, bool, error)
- func CurrentRustPackedCellEntry(cacheRoot, key string, extensions []RustExtension) (string, bool, error)
- func ExtPackageName(name string) string
- func GoSDKPathOverride(root string) string
- func HasCacheEntries(cacheRoot string) (bool, error)
- func MarkArtifactUsed(artifactPath string, now time.Time) error
- func ResolvePrebuilt(req PrebuiltRequest) (string, bool)
- func RustSDKPathOverride(root string) string
- func SetPrebuiltResolver(r PrebuiltResolver)
- func SocketEnvName(name string) string
- func StageLegacyGoSDK(sdkRoot, dst string) error
- func TouchUsage(entryDir string, now time.Time) error
- func ValidEntry(entryDir string, want EntryIdentity) (string, bool)
- type CacheClass
- type CacheEntry
- type CacheLifecycleOptions
- type CacheReport
- type EntryIdentity
- type GoExtension
- type GoPackedCell
- type PrebuiltExtension
- type PrebuiltRequest
- type PrebuiltResolver
- type PublishedEntry
- type PythonExtension
- type PythonPackedCell
- type RustExtension
- type RustPackedCell
- type UsageLease
- type UsageMetadata
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ArtifactIdentity ¶
ArtifactIdentity returns the immutable digest recorded when an entry was published.
func CurrentGoPackedCellEntry ¶
func CurrentGoPackedCellEntry(cacheRoot, key string, extensions []GoExtension) (string, bool, error)
CurrentGoPackedCellEntry returns the valid cache entry selected by the same normalization and hash inputs as BuildGoPackedCell, without building it.
func CurrentPythonPackedCellEntry ¶
func CurrentPythonPackedCellEntry(cacheRoot, key string, extensions []PythonExtension) (string, bool, error)
CurrentPythonPackedCellEntry returns the valid cache entry selected by the same normalization and hash inputs as BuildPythonPackedCell, without building it.
func CurrentRustPackedCellEntry ¶
func CurrentRustPackedCellEntry(cacheRoot, key string, extensions []RustExtension) (string, bool, error)
CurrentRustPackedCellEntry returns the valid cache entry selected by the same normalization and hash inputs as BuildRustPackedCell, without building it.
func ExtPackageName ¶
ExtPackageName returns a deterministic import alias for a generated packed or fused extension registry.
func GoSDKPathOverride ¶
GoSDKPathOverride returns an extension module's explicit local SDK replace.
func HasCacheEntries ¶
HasCacheEntries reports whether PruneCaches and InspectCache would classify at least one entry under cacheRoot.
func ResolvePrebuilt ¶
func ResolvePrebuilt(req PrebuiltRequest) (string, bool)
ResolvePrebuilt exposes the process-wide prebuilt-cell resolver to other host packages (e.g. the source-mode subprocess builder). Returns ("", false) when no resolver is registered, so stock pig behavior is unchanged.
func RustSDKPathOverride ¶
RustSDKPathOverride returns an extension crate's explicit local SDK path.
func SetPrebuiltResolver ¶
func SetPrebuiltResolver(r PrebuiltResolver)
SetPrebuiltResolver installs the process-wide prebuilt-cell resolver, or nil to restore the default from-source behavior.
func SocketEnvName ¶
SocketEnvName returns the environment variable used to pass one extension's socket into a packed-cell runner.
func StageLegacyGoSDK ¶
StageLegacyGoSDK copies the SDK module and its subpackages into dst under the legacy import path. Self-imports follow the alias, including internal packages. Authored SDK sources remain untouched. pig additive (D19): legacy Go imports use the running host's SDK contract.
func ValidEntry ¶
func ValidEntry(entryDir string, want EntryIdentity) (string, bool)
ValidEntry reports whether a cache directory contains a complete artifact published for want on this platform.
Types ¶
type CacheClass ¶
type CacheClass string
const ( CacheActive CacheClass = "active" CacheCurrent CacheClass = "current" CacheBuilding CacheClass = "building" CacheInactiveRetained CacheClass = "inactive-retained" CacheInactiveExpired CacheClass = "inactive-expired" CacheInvalid CacheClass = "incomplete/invalid" )
type CacheEntry ¶
type CacheEntry struct {
Path string `json:"path"`
Class CacheClass `json:"class"`
Bytes int64 `json:"bytes"`
LastUsed int64 `json:"lastUsed,omitempty"`
Reason string `json:"reason,omitempty"`
}
type CacheLifecycleOptions ¶
type CacheReport ¶
type CacheReport struct {
Entries []CacheEntry `json:"entries"`
ByClass map[CacheClass]int `json:"byClass"`
TotalBytes int64 `json:"totalBytes"`
RemovedBytes int64 `json:"removedBytes"`
Removed int `json:"removed"`
ProtectedBytes int64 `json:"protectedBytes"`
LimitSatisfied bool `json:"limitSatisfied"`
Errors []string `json:"errors,omitempty"`
}
func InspectCache ¶
func InspectCache(options CacheLifecycleOptions) (CacheReport, error)
func PruneCaches ¶
func PruneCaches(options CacheLifecycleOptions) (CacheReport, error)
type EntryIdentity ¶
EntryIdentity is the publication identity a caller expects of a cache entry: the input digest that names it, its canonical artifact filename, and the language that built it.
type GoExtension ¶
type GoExtension struct {
Name string
Root string
ModulePath string
Package string
Factory string
Hash string
WorkspaceModules []string
}
GoExtension describes one factory-style Go SDK extension that can be packed into a generated subprocess runner. The extension package must expose a factory function with signature:
func Extension() *sdk.Extension
or the Factory name supplied here.
type GoPackedCell ¶
type GoPackedCell struct {
Key string
Hash string
CacheDir string
BinaryPath string
Cached bool
BuildDuration time.Duration
Extensions []GoExtension
// Generation is this spawn attempt's packed-cell generation number
// (pig additive, CNC-002), claimed by the caller before any build work so
// an async crash report for a process this attempt is replacing cannot
// mistake itself for still current. Zero (the default, for callers that
// never claim one) makes the host claim the generation at spawn.
Generation int
}
GoPackedCell describes a generated runner artifact. Packing is an execution optimization only: the generated binary is still a subprocess and each contained extension uses its own host socket.
func BuildGoPackedCell ¶
func BuildGoPackedCell(ctx context.Context, cacheRoot, key string, extensions []GoExtension) (*GoPackedCell, error)
BuildGoPackedCell generates and builds a Go runner that hosts multiple factory-style Go SDK extensions in one subprocess artifact. The artifact is cached by a deterministic cell hash derived from the extension hashes and factory/package metadata.
func BuildGoPackedCellWithSDKRoot ¶
func BuildGoPackedCellWithSDKRoot(ctx context.Context, cacheRoot, key string, extensions []GoExtension, preferredSDKRoot string) (*GoPackedCell, error)
BuildGoPackedCellWithSDKRoot builds a packed cell using preferredSDKRoot when the extensions do not declare their own valid SDK replacement. Hosts use this to keep packed builds on the running process's resolved config root.
type PrebuiltExtension ¶
PrebuiltExtension identifies one extension inside a cell composition.
type PrebuiltRequest ¶
type PrebuiltRequest struct {
Language string // "go" | "rust" | "python"
Key string // cell key (pack group)
GOOS string
GOARCH string
Extensions []PrebuiltExtension
}
PrebuiltRequest describes the packed cell the host is about to build.
type PrebuiltResolver ¶
type PrebuiltResolver interface {
ResolvePrebuilt(PrebuiltRequest) (binaryPath string, ok bool)
}
PrebuiltResolver maps a cell composition to an already-built binary. The resolver owns the match policy (e.g. how strictly to compare pinned hashes); the host only supplies the composition it is about to build.
type PublishedEntry ¶
type PublishedEntry struct {
Dir string
ArtifactPath string
Reused bool // an existing valid entry satisfied the request without building
}
PublishedEntry is the result of resolving a content-addressed cache entry.
func PublishArtifact ¶
func PublishArtifact(ctx context.Context, finalDir, canonicalName, inputDigest, language string, build func(scratch string) (artifactPath string, err error), keepAlso ...string) (PublishedEntry, error)
PublishArtifact deduplicates construction of a content-addressed cache entry across processes, for packed runtime cells and for compiled source-mode extension binaries alike. finalDir is the entry directory (named by inputDigest); canonicalName is the single published artifact's filename. build runs inside a private scratch directory and returns the finished primary artifact. The artifact can live in an external compiler cache; publication copies it into scratch before atomically renaming the complete entry.
Exactly one process builds a given finalDir: callers take a per-digest advisory lock (released automatically on process death, so a crash never wedges the cache), re-check the cache under the lock, then build into private scratch and publish with a single atomic rename. Readers therefore never observe a half-written entry, distinct Pig instances share one built artifact instead of each rebuilding it, and only {canonicalName, ready.json} is retained - compiler intermediates (generated source, Rust target/) are discarded.
func ReusePublishedArtifact ¶
func ReusePublishedArtifact(finalDir string, want EntryIdentity) (PublishedEntry, bool)
ReusePublishedArtifact returns the complete entry at finalDir published for want, if one exists, and records its use. It never builds or waits for a lock.
type PythonExtension ¶
PythonExtension describes one factory-style Python SDK extension that can be packed into a generated subprocess runner. The module must expose a factory returning pig_sdk.Extension, typically:
def new_extension() -> pig_sdk.Extension
The generated runner is a Python subprocess and uses one socket per contained extension.
type PythonPackedCell ¶
type PythonPackedCell struct {
Key string
Hash string
CacheDir string
BinaryPath string
Cached bool
BuildDuration time.Duration
Extensions []PythonExtension
}
PythonPackedCell describes a generated Python packed-cell artifact.
func BuildPythonPackedCell ¶
func BuildPythonPackedCell(ctx context.Context, cacheRoot, key string, extensions []PythonExtension) (*PythonPackedCell, error)
type RustExtension ¶
type RustExtension struct {
Name string
Root string
Package string
Crate string
Factory string
Hash string
}
RustExtension describes one factory-style Rust SDK extension that can be packed into a generated subprocess runner. The crate must expose a factory function returning pig_sdk::Extension, typically:
pub fn new_extension() -> pig_sdk::Extension
The generated runner still runs as a subprocess and uses one socket per contained extension.
type RustPackedCell ¶
type RustPackedCell struct {
Key string
Hash string
CacheDir string
BinaryPath string
Cached bool
BuildDuration time.Duration
Extensions []RustExtension
}
RustPackedCell describes a generated Rust packed-cell artifact.
func BuildRustPackedCell ¶
func BuildRustPackedCell(ctx context.Context, cacheRoot, key string, extensions []RustExtension) (*RustPackedCell, error)
BuildRustPackedCell generates and builds a Cargo runner that hosts multiple factory-style Rust SDK extensions in one subprocess artifact.
type UsageLease ¶
type UsageLease struct {
// contains filtered or unexported fields
}
func AcquireArtifactUsageLease ¶
func AcquireArtifactUsageLease(artifactPath string) (*UsageLease, error)
func AcquireUsageLease ¶
func AcquireUsageLease(entryDir string) (*UsageLease, error)
func (*UsageLease) Release ¶
func (l *UsageLease) Release() error
type UsageMetadata ¶
type UsageMetadata struct {
LastUsed int64 `json:"lastUsed"`
}