service

Documentation

Overview

Package service contains models for backends and compilers (external services, hence the name).

Index

• func RunAndCaptureStdout(ctx context.Context, r Runner, ri RunInfo) (string, error)
• type ExtClass
  • func (e ExtClass) ProbeByVersionCommand(ctx context.Context, r Runner, args ...string) map[string]string
• type RunInfo
  • func NewRunInfo(cmd string, args ...string) *RunInfo
  • func (r *RunInfo) AppendArgs(new ...string)
  • func (r *RunInfo) EnvStrings() []string
  • func (r *RunInfo) Interpolate(expansions map[string]string) error
  • func (r *RunInfo) Invocation() []string
  • func (r *RunInfo) NewIfDifferent(cmd string) *RunInfo
  • func (r *RunInfo) Override(new RunInfo)
  • func (r *RunInfo) OverrideIfNotNil(new *RunInfo)
  • func (r *RunInfo) String() string
  • func (r *RunInfo) SystematicID() (id.ID, error)
• type Runner

Examples

• RunInfo.Interpolate
• RunInfo.Override
• RunInfo.SystematicID

Functions

func RunAndCaptureStdout

func RunAndCaptureStdout(ctx context.Context, r Runner, ri RunInfo) (string, error)

RunAndCaptureStdout runs r with ctx and ri, and captures its stdout to a string. This behaviour overrides any previous stdout capture for the runner.

Types

type ExtClass

type ExtClass struct {
	// DefaultRunInfo captures the default run information for this class.
	DefaultRunInfo RunInfo

	// AltCommands contains possible alternative commands that can be substituted into DefaultRunInfo.
	// This is mainly for probing purposes.
	AltCommands []string
}

ExtClass contains fields common to a service class that invokes an external binary.

func (ExtClass) ProbeByVersionCommand

func (e ExtClass) ProbeByVersionCommand(ctx context.Context, r Runner, args ...string) map[string]string

ProbeByVersionCommand runs a version command for every command in this ExtClass's DefaultRunInfo and AltCommands, formed by appending args to the DefaultRunInfo arguments. It returns a map from command names to versions, where a command name is mapped only if the version command succeeded.

type RunInfo

type RunInfo struct {
	// Cmd overrides the command for the service.
	Cmd string `toml:"cmd,omitzero" json:"cmd,omitempty"`

	// Args specifies (extra) arguments to supply to the service.
	Args []string `toml:"args,omitempty" json:"args,omitempty"`

	// Env defines environment variables to be set if the runner supports it.
	Env map[string]string `toml:"env,omitempty" json:"env,omitempty"`
}

RunInfo gives hints as to how to run a service.

func NewRunInfo

func NewRunInfo(cmd string, args ...string) *RunInfo

NewRunInfo programmatically creates a RunInfo using command cmd and arguments args.

func (*RunInfo) AppendArgs

func (r *RunInfo) AppendArgs(new ...string)

AppendArgs overlays new arguments onto this run info.

func (*RunInfo) EnvStrings

func (r *RunInfo) EnvStrings() []string

EnvStrings is the environment as a set of key-value pairs. This is compatible with exec.Cmd's Env field.

func (*RunInfo) Interpolate

func (r *RunInfo) Interpolate(expansions map[string]string) error

Interpolate expands any interpolations in this run info's arguments and environment according to expansions. While it modifies this RunInfo in place, it creates a new argument slice and environment map.

Example

ExampleRunInfo_Interpolate is a runnable example for the Interpolate method.

package main

import (
	"fmt"

	"github.com/c4-project/c4t/internal/model/service"
)

func main() {
	r1 := service.RunInfo{
		Cmd:  "gcc",
		Args: []string{"-std=${standard}"},
		Env:  map[string]string{"C4_MUTATION": "${mutant}"},
	}
	// Shallow copies shouldn't be affected by the interpolation
	r2 := r1
	_ = r1.Interpolate(map[string]string{"standard": "c11", "mutant": "4"})
	_ = r2.Interpolate(map[string]string{"standard": "c99", "mutant": "3"})

	fmt.Println(&r1)
	fmt.Println(&r2)

}

Output:

C4_MUTATION=4 gcc -std=c11
C4_MUTATION=3 gcc -std=c99

func (*RunInfo) Invocation

func (r *RunInfo) Invocation() []string

Invocation is Cmd appended to Args.

func (*RunInfo) NewIfDifferent

func (r *RunInfo) NewIfDifferent(cmd string) *RunInfo

NewIfDifferent returns a new RunInfo overriding this RunInfo's Cmd with cmd if it is different, and nil otherwise. This is useful for generating service configuration, if we only want to supply a specific non-default RunInfo when there is a real difference from the current default.

This function may eventually also take arguments; if so, they will be supplied variadically.

func (*RunInfo) Override

func (r *RunInfo) Override(new RunInfo)

Override overlays this run information with that in new.

Example

ExampleRunInfo_Override is a runnable example for the Override method.

package main

import (
	"fmt"

	"github.com/c4-project/c4t/internal/model/service"
)

func main() {
	r1 := &service.RunInfo{
		Cmd:  "gcc",
		Args: []string{"-std=c11", "-pthread"},
		Env:  map[string]string{"FOO": "baz"},
	}
	r1.Override(service.RunInfo{
		Cmd:  "clang",
		Args: []string{"-pedantic"},
	})
	r1.Override(service.RunInfo{
		Cmd:  "",
		Args: []string{"-funroll-loops"},
		Env:  map[string]string{"FOO": "", "BAR": "baz"},
	})

	fmt.Println(r1)

}

Output:

BAR=baz FOO= clang -std=c11 -pthread -pedantic -funroll-loops

func (*RunInfo) OverrideIfNotNil

func (r *RunInfo) OverrideIfNotNil(new *RunInfo)

OverrideIfNotNil is Override if new is non-nil, and no-op otherwise.

func (*RunInfo) String

func (r *RunInfo) String() string

String is defined as the space-joined form of EnvString and Invocation.

func (*RunInfo) SystematicID

func (r *RunInfo) SystematicID() (id.ID, error)

SystematicID produces an ID based any present elements of this RunInfo. If the RunInfo is the zero value, the ID will be empty. It is not formally guaranteed to be unique, but should be close enough.

Example

ExampleRunInfo_SystematicID is a runnable example for the SystematicID method.

package main

import (
	"fmt"

	"github.com/c4-project/c4t/internal/model/service"
)

func main() {
	r := service.RunInfo{
		Cmd:  "gcc",
		Args: []string{"-std=c11"},
		Env:  map[string]string{"C4_MUTATION": "4"},
	}

	id1, _ := r.SystematicID()
	fmt.Println(id1)

	// If the command is empty, it doesn't appear in the ID anymore
	r.Cmd = ""
	id2, _ := r.SystematicID()
	fmt.Println(id2)

}

Output:

gcc.-std=c11.c4_mutation=4
-std=c11.c4_mutation=4

type Runner

type Runner interface {
	// WithStdout should return a new runner with the standard output overridden to w.
	WithStdout(w io.Writer) Runner

	// WithStderr should return a new runner with the standard error overridden to w.
	WithStderr(w io.Writer) Runner

	// WithGrace should return a new runner with the timeout grace period set to d.
	WithGrace(d time.Duration) Runner

	// Run runs r using context ctx.
	Run(ctx context.Context, r RunInfo) error
}

Runner is the interface of things that can run, or pretend to run, services.