Documentation
¶
Index ¶
- Constants
- func GeneratePetName() string
- func GetLogsDir(sessionID string) (string, error)
- func GetPIDsDir(sessionID string) (string, error)
- func GetPlaygroundDir() (string, error)
- func GetSessionTempDirCount() int
- func GetSessionsDir() (string, error)
- func MustGetPlaygroundTempDir() string
- func MustGetTempSessionDir(sessionID string) string
- func MustGetVolumeDir(sessionID, volumeName string) string
- func NotifyDetachReady(fd int, logPath string) error
- func RedirectStdio(logPath string) error
- func SignalReady(fd int) error
- func StartTimer(name string) func()
- func StripFlag(args []string, flag string, takesValue bool) []string
- func TempPlaygroundDirPath() string
- type DetachForkOptions
- type DetachedChild
Constants ¶
const DefaultNotifyFlag = "--detached-notify-fd"
DefaultNotifyFlag is the CLI flag used to pass the notify fd to a re-exec'd child when DetachForkOptions.NotifyFlag is left empty.
const ReadyMarker = "READY"
ReadyMarker is the line a re-exec'd child writes to its notify fd to tell its parent that startup is complete and it is safe to detach.
Variables ¶
This section is empty.
Functions ¶
func GeneratePetName ¶
func GeneratePetName() string
GeneratePetName generates a random pet name like perfect-bee. These names are useful as human friendly identifiers.
func GetLogsDir ¶ added in v0.3.2
GetLogsDir returns the directory where service logs are stored.
func GetPIDsDir ¶ added in v0.3.2
GetPIDsDir returns the directory where pid files are stored for a session.
func GetPlaygroundDir ¶ added in v0.3.2
GetPlaygroundDir returns the base directory for builder-playground state. It follows XDG Base Directory Specification, defaulting to ~/.local/state/builder-playground.
func GetSessionTempDirCount ¶ added in v0.3.2
func GetSessionTempDirCount() int
GetSessionTempDirCount returns the number of session directories under the playground temp dir.
func GetSessionsDir ¶ added in v0.3.2
GetSessionsDir returns the directory for all sessions.
func MustGetPlaygroundTempDir ¶ added in v0.3.2
func MustGetPlaygroundTempDir() string
MustGetPlaygroundTempDir creates the temp dir for
func MustGetTempSessionDir ¶ added in v0.3.2
MustGetSessionTempDir creates and returns the temp dir for the session under the temp playground dir.
func MustGetVolumeDir ¶ added in v0.3.2
MustGetVolumeDir creates and returns the temp dir for bind mount volumes under the temp session dir.
func NotifyDetachReady ¶ added in v0.3.2
NotifyDetachReady is a convenience that calls SignalReady followed by RedirectStdio — the full sequence a re-exec'd child performs once it has finished bringing its services up.
func RedirectStdio ¶ added in v0.3.2
RedirectStdio points the current process's stdin at /dev/null and stdout and stderr at logPath (opened in append mode, creating it if needed). If logPath is empty, stdout and stderr are redirected to /dev/null as well. Existing file descriptors for stdout/stderr are atomically replaced via dup2, so Go code that captured os.Stdout/os.Stderr before the call continues to write to the redirected target.
func SignalReady ¶ added in v0.3.2
SignalReady writes ReadyMarker (followed by a newline) to fd and closes it. The fd must be a writable pipe whose read end is held by the parent. After this call the caller must not use fd again.
func StartTimer ¶
func StartTimer(name string) func()
StartTimer starts a timer with the given name and returns a function that prints the elapsed time when called. The elapsed time is only printed if debug or trace levels are used.
func StripFlag ¶ added in v0.3.2
StripFlag returns args with any occurrence of --flag, --flag=value, or the two-token form --flag value removed. It is intended for trimming a parent mode flag (e.g. --detached) out of os.Args before handing them to a child via DetachFork.
func TempPlaygroundDirPath ¶ added in v0.3.2
func TempPlaygroundDirPath() string
TempPlaygroundDirPath returns the temp playground dir path.
Types ¶
type DetachForkOptions ¶ added in v0.3.2
type DetachForkOptions struct {
// Executable is the binary to launch. Required.
Executable string
// Args are the CLI args passed to the child (not including argv[0]).
// Callers are responsible for stripping any flag that would cause the
// child to recurse back into parent-mode (e.g. --detached).
Args []string
// NotifyFlag is the flag appended to Args telling the child which fd
// carries the ready pipe. "=<fd>" is appended automatically. If empty,
// DefaultNotifyFlag is used.
NotifyFlag string
// Env is the environment passed to the child. If nil, the child inherits
// the current process's environment.
Env []string
// Stdout and Stderr are inherited by the child so the user sees startup
// logs live. Default to os.Stdout and os.Stderr.
Stdout *os.File
Stderr *os.File
// ForwardSignals lists signals forwarded to the child while the parent is
// waiting for readiness, so Ctrl-C during startup still tears things down
// cleanly. Defaults to SIGINT, SIGTERM, SIGHUP, SIGQUIT.
ForwardSignals []os.Signal
}
DetachForkOptions configures DetachFork.
type DetachedChild ¶ added in v0.3.2
type DetachedChild struct {
PID int
}
DetachedChild is the handle returned once the child has signaled readiness. The parent has already released the process (no reaping required) and can exit freely; the child keeps running in its own session.
func DetachFork ¶ added in v0.3.2
func DetachFork(opts DetachForkOptions) (*DetachedChild, error)
DetachFork re-execs Executable as a child process, attaches a one-shot readiness pipe to fd 3 in the child, and blocks until the child writes ReadyMarker to that pipe. On success the child is released and the returned DetachedChild reports its PID. If the child exits or closes the pipe before signaling ready, an error is returned.
Source Files
Directories