Documentation
¶
Overview ¶
Package hyperlight is the Hyperlight backend: every fiber is a Hyperlight micro-VM restored from a snapshot of the warm guest, held by a helper process that fiberd starts per grant and drives over the line protocol in hack/hyperlight/PROTOCOL.md. Hyperlight has a Rust host API only, so the mechanism lives in the helper (hack/hyperlight/helper); the same protocol is served without a hypervisor by hack/hyperlight/fakehelper, which conformance runs against and the unit tests run inside their own process through the starter.
The helper's sandboxes are threads of one process, so a fiber has no process and no cgroup leaf of its own: the helper runs in the grant's cgroup (the ceiling still holds), exits are reported by fence, and W is what the helper reports the guest dirtied (backend.WReporter). Tier FIBER_SNAPSHOT. No delta codec: a park is what the helper wrote.
A grant with a device engine hands the helper the engine's socket. A guest reaches it only through the helper, which puts the fiber's fence in each request, so the helper's cgroup speaks for every fiber and the host sends the engine RELAY for it (RelaysEngine).
A template artifact may carry the guest's snapshot as its images (artifact.ImagesFormatHyperlight). The host opens a read-only copy of it for each warm (SnapshotRestorer), and the helper restores the warm instance from it, given as --template-dir.
Index ¶
- Variables
- func HelperFlag(arg string) bool
- func New(o Options) backend.Backend
- func PlatformOf(version string) (artifact.Platform, error)
- type Backend
- func (b *Backend) Clone(ctx context.Context, warmID string, sp backend.FiberSpec) (backend.Fiber, error)
- func (b *Backend) Close()
- func (b *Backend) DefaultDeadlines(warmID string) (create, resume time.Duration)
- func (b *Backend) Exits() <-chan backend.Exit
- func (b *Backend) FiberOverheadBytes() uint64
- func (b *Backend) FiberW(fiberID string) (uint64, bool)
- func (b *Backend) ImagesFormat() string
- func (b *Backend) IsolatesTenants() bool
- func (b *Backend) Kill(fiberID string) error
- func (b *Backend) Name() string
- func (b *Backend) Park(ctx context.Context, fiberID string, sp backend.ParkSpec) error
- func (b *Backend) Platform() artifact.Platform
- func (b *Backend) ProbeErr() error
- func (b *Backend) RelaysEngine() bool
- func (b *Backend) Resume(ctx context.Context, sp backend.ResumeSpec) (backend.Fiber, error)
- func (b *Backend) Tier() core.Tier
- func (b *Backend) Unwarm(id string)
- func (b *Backend) Warm(ctx context.Context, sp backend.WarmSpec) (backend.Warm, error)
- type Options
Constants ¶
This section is empty.
Variables ¶
var ErrHelper = errors.New("hyperlight: helper error")
Functions ¶
func HelperFlag ¶
HelperFlag reports whether arg, a template argument, is one of the flags fiberd itself gives the helper (--guest, --engine, --template-dir) as the protocol's argument grammar reads it (hack/hyperlight/PROTOCOL.md): after one dash or two, the name up to any =. A helper reads no more than that grammar, so no other argument can name a flag, and a helper whose last flag wins never takes the guest, engine or snapshot a template's author named over fiberd's.
func New ¶
New opens the backend. The tier is FIBER_SNAPSHOT when the helper answers `--version` and the guest exists. Otherwise it offers none, and ProbeErr says why.
func PlatformOf ¶
PlatformOf is the platform a Hyperlight home records for snapshots made through the helper whose `--version` printed version: its facts, mapped as the backend's Platform maps them. A build of a Hyperlight snapshot artifact records it (artifact.BuildOptions.HyperlightSnapshot), so the parity a home checks is against the helper it runs, not the host the artifact was built on.
Types ¶
type Backend ¶
type Backend struct {
// contains filtered or unexported fields
}
Backend implements backend.Backend, Platformer, DeadlineAdvisor, WReporter and Prober.
func (*Backend) Clone ¶
func (b *Backend) Clone(ctx context.Context, warmID string, sp backend.FiberSpec) (backend.Fiber, error)
Clone asks the helper for a fiber from the warm snapshot, told its generation and a fresh seed before it serves.
func (*Backend) DefaultDeadlines ¶
DefaultDeadlines sizes the deadlines of a clone or resume without one of its own from the probe clone the warm instance made. They are the floors, raised to deadlineFactor times the probe and capped at deadlineCap. An instance whose probe measured nothing, or one this backend does not have, gets the floors.
func (*Backend) FiberOverheadBytes ¶
FiberOverheadBytes: a fiber here is a whole sandbox restored from the template's snapshot, not a copy-on-write child, so it costs about what the warm instance costs however little of it the guest dirties. W stays the dirtied bytes the helper reports; this is what the grant's block ceiling must leave room for, and 0 asks the host to measure it from the warm instance rather than guess. Without it the ceiling is sized as if a fiber cost only its W budget, and the first clone puts the grant cgroup over memory.high: the ladder then sheds and yields while the helper crawls, which is what a park that never came back looked like.
func (*Backend) ImagesFormat ¶
ImagesFormat implements backend.SnapshotRestorer: the helper restores a Hyperlight snapshot a template artifact carries (--template-dir) when it is usable and its --version says so (restoresLine). Any other helper restores none, so the host refuses such a template rather than open its snapshot for a helper that might ignore the flag and warm its own guest under the template's digest.
func (*Backend) IsolatesTenants ¶
IsolatesTenants is true because a fiber is a micro-VM guest behind the hypervisor.
func (*Backend) Platform ¶
Platform reports the helper's facts, because a snapshot depends on them and not on the host kernel or libc. A backend without a usable helper warms nothing, and says so here.
func (*Backend) ProbeErr ¶
ProbeErr is why New found no tier: the helper cannot state its facts, or the guest is missing.
func (*Backend) RelaysEngine ¶
RelaysEngine is true because a fiber has no process of its own. Its engine requests come from the helper, in the warm instance's cgroup, with the fiber's fence put in by the helper, never by the guest.
type Options ¶
type Options struct {
// Helper is the helper executable (the Rust helper, or fakehelper).
// Required.
Helper string
// Guest is the guest binary the helper loads; template commands from
// -template are appended to the helper's arguments after it.
Guest string
}
Options configure the Hyperlight backend.
Source Files