bind

Documentation

Overview

Package bind contains code for binding to and controlling devices.

Index

• Constants
• func PutRegistry(ctx context.Context, m *Registry) context.Context
• type Device
  • func Host(ctx context.Context) Device
• type DeviceListener
  • func NewDeviceListener(onDeviceAdded, onDeviceRemoved func(context.Context, Device)) DeviceListener
• type Registry
  • func GetRegistry(ctx context.Context) *Registry
  • func NewRegistry() *Registry
  • func (r *Registry) AddDevice(ctx context.Context, d Device)
  • func (r *Registry) DefaultDevice() Device
  • func (r *Registry) Device(id id.ID) Device
  • func (r *Registry) DeviceProperty(ctx context.Context, d Device, k interface{}) interface{}
  • func (r *Registry) Devices() []Device
  • func (r *Registry) Listen(l DeviceListener) (unregister func())
  • func (r *Registry) RemoveDevice(ctx context.Context, d Device)
  • func (r *Registry) SetDeviceProperty(ctx context.Context, d Device, k, v interface{})
• type Simple
  • func (b *Simple) ABI() *device.ABI
  • func (b *Simple) CanTrace() bool
  • func (b *Simple) ConnectPerfetto(ctx context.Context) (*perfetto.Client, error)
  • func (b *Simple) FileContents(ctx context.Context, path string) (string, error)
  • func (b *Simple) GetEnv(ctx context.Context) (*shell.Env, error)
  • func (b *Simple) GetURIRoot() string
  • func (b *Simple) GetWorkingDirectory(ctx context.Context) (string, error)
  • func (b *Simple) Instance() *device.Instance
  • func (b *Simple) IsDirectory(ctx context.Context, path string) (bool, error)
  • func (b *Simple) IsFile(ctx context.Context, path string) (bool, error)
  • func (b *Simple) IsLocal(ctx context.Context) (bool, error)
  • func (b *Simple) ListDirectories(ctx context.Context, path string) ([]string, error)
  • func (b *Simple) ListExecutables(ctx context.Context, path string) ([]string, error)
  • func (b *Simple) PushFile(ctx context.Context, sourcePath, destPath string) error
  • func (b *Simple) RemoveFile(ctx context.Context, path string) error
  • func (b *Simple) SetupLocalPort(ctx context.Context, port int) (int, error)
  • func (b *Simple) Shell(name string, args ...string) shell.Cmd
  • func (b *Simple) Status(ctx context.Context) Status
  • func (b *Simple) String() string
  • func (b *Simple) SupportsPerfetto(ctx context.Context) bool
  • func (b *Simple) TempDir(ctx context.Context) (string, app.Cleanup, error)
  • func (b *Simple) TempFile(ctx context.Context) (string, func(ctx context.Context), error)
  • func (b *Simple) WriteFile(ctx context.Context, contents io.Reader, mode os.FileMode, destPath string) error

Constants

const (
	// ErrShellNotSupported may be returned by Start if the target does not support a shell.
	ErrShellNotSupported = fault.Const("bind.Simple does not support shell commands")
)

Functions

func PutRegistry

func PutRegistry(ctx context.Context, m *Registry) context.Context

PutRegistry attaches a registry to a Context.

Types

type Device

type Device interface {
	// Instance returns the instance information for this device.
	Instance() *device.Instance
	// State returns the last known connected status of the device.
	Status(ctx context.Context) Status
	// Shell is a helper that builds a shell.Cmd with d.ShellTarget() as its target
	Shell(name string, args ...string) shell.Cmd
	// TempFile creates a temporary file on the given Device. It returns the
	// path to the file, and a function that can be called to clean it up.
	TempFile(ctx context.Context) (string, func(ctx context.Context), error)
	// TempDir makes a temporary directory, and returns the
	// path, as well as a function to call to clean it up.
	TempDir(ctx context.Context) (string, app.Cleanup, error)
	// FileContents returns the contents of a given file on the Device.
	FileContents(ctx context.Context, path string) (string, error)
	// RemoveFile removes the given file from the device
	RemoveFile(ctx context.Context, path string) error
	// GetEnv returns the default environment for the Device.
	GetEnv(ctx context.Context) (*shell.Env, error)
	// SetupLocalPort makes sure that the given port can be accessed on localhost
	// It returns a new port number to connect to on localhost
	SetupLocalPort(ctx context.Context, port int) (int, error)
	// ListExecutables returns the executables in a particular directory as given by path
	ListExecutables(ctx context.Context, path string) ([]string, error)
	// ListDirectories returns a list of directories rooted at a particular path
	ListDirectories(ctx context.Context, path string) ([]string, error)
	// GetURIRoot returns the root URI for the entire system
	GetURIRoot() string
	// IsFile returns true if the given path is a file
	IsFile(ctx context.Context, path string) (bool, error)
	// IsDirectory returns true if the given path is a directory
	IsDirectory(ctx context.Context, path string) (bool, error)
	// GetWorkingDirectory returns the directory that this device considers CWD
	GetWorkingDirectory(ctx context.Context) (string, error)
	// IsLocal returns true if this tracer is local
	IsLocal(ctx context.Context) (bool, error)
	// CanTrace returns true if this device can be used to take a trace
	CanTrace() bool
	// SupportsPerfetto returns true if this device will work with perfetto
	SupportsPerfetto(ctx context.Context) bool
	// ConnectPerfetto connects to a Perfetto service running on this device
	// and returns an open socket connection to the service.
	ConnectPerfetto(ctx context.Context) (*perfetto.Client, error)
	// PushFile will transfer the local file at sourcePath to the remote
	// machine at destPath
	PushFile(ctx context.Context, sourcePath, destPath string) error
	// WriteFile writes the given file into the given location on the remote device
	WriteFile(ctx context.Context, contents io.Reader, mode os.FileMode, destPath string) error
}

Device represents a connection to an attached device.

func Host

func Host(ctx context.Context) Device

Host returns the Device to the host.

type DeviceListener

type DeviceListener interface {
	OnDeviceAdded(context.Context, Device)
	OnDeviceRemoved(context.Context, Device)
}

DeviceListener is the interface implemented by types that respond to devices being added to and removed from the registry.

func NewDeviceListener

func NewDeviceListener(onDeviceAdded, onDeviceRemoved func(context.Context, Device)) DeviceListener

NewDeviceListener returns a DeviceListener that delegates calls on to onDeviceAdded and onDeviceRemoved.

type Registry

type Registry struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Registry is holds a list of registered devices. It provides methods for listening for devices that are added to and removed from the device.

func GetRegistry

func GetRegistry(ctx context.Context) *Registry

GetRegistry retrieves the registry from a context previously annotated by PutRegistry.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns a newly constructed Registry.

func (*Registry) AddDevice

func (r *Registry) AddDevice(ctx context.Context, d Device)

AddDevice registers the device dev with the Registry.

func (*Registry) DefaultDevice

func (r *Registry) DefaultDevice() Device

DefaultDevice returns the first device registered with the Registry.

func (*Registry) Device

func (r *Registry) Device(id id.ID) Device

Device looks up the device with the specified identifier. If no device with the specified identifier was registered with the Registry then nil is returner.

func (*Registry) DeviceProperty

func (r *Registry) DeviceProperty(ctx context.Context, d Device, k interface{}) interface{}

DeviceProperty returns the property with the key k for the device d, previously set with SetDeviceProperty. If the property for the device does not exist then nil is returned.

func (*Registry) Devices

func (r *Registry) Devices() []Device

Devices returns the list of devices registered with the Registry.

func (*Registry) Listen

func (r *Registry) Listen(l DeviceListener) (unregister func())

Listen registers l to be called whenever a device is added to or removed from the registry. l will be unregistered when the returned function is called.

func (*Registry) RemoveDevice

func (r *Registry) RemoveDevice(ctx context.Context, d Device)

RemoveDevice unregisters the device d with the Registry.

func (*Registry) SetDeviceProperty

func (r *Registry) SetDeviceProperty(ctx context.Context, d Device, k, v interface{})

SetDeviceProperty sets the property with the key k to the value v for the device d. This property can be retrieved with DeviceProperty. Properties will persist in the registry even when the device has not been added or has been removed.

type Simple

type Simple struct {
	To         *device.Instance
	LastStatus Status
}

Simple is a very short implementation of the Device interface. It directly holds the devices Information struct, and its last known Status, but provides no other active functionality. It can be used for fake devices, or as a building block to create a more complete device.

func (*Simple) ABI

func (b *Simple) ABI() *device.ABI

ABI implements the Device interface returning the first ABI from the Information, or UnknownABI if it has none.

func (*Simple) CanTrace

func (b *Simple) CanTrace() bool

CanTrace returns true if this device can be used to take a trace

func (*Simple) ConnectPerfetto

func (b *Simple) ConnectPerfetto(ctx context.Context) (*perfetto.Client, error)

ConnectPerfetto connects to a Perfetto service running on this device and returns an open socket connection to the service.

func (*Simple) FileContents

func (b *Simple) FileContents(ctx context.Context, path string) (string, error)

FileContents returns the contents of a given file on the Device.

func (*Simple) GetEnv

func (b *Simple) GetEnv(ctx context.Context) (*shell.Env, error)

GetEnv returns the default environment for the Device.

func (*Simple) GetURIRoot

func (b *Simple) GetURIRoot() string

GetURIRoot returns the root URI for the entire system

func (*Simple) GetWorkingDirectory

func (b *Simple) GetWorkingDirectory(ctx context.Context) (string, error)

GetWorkingDirectory returns the directory that this device considers CWD

func (*Simple) Instance

func (b *Simple) Instance() *device.Instance

Instance implements the Device interface returning the Information in the To field.

func (*Simple) IsDirectory

func (b *Simple) IsDirectory(ctx context.Context, path string) (bool, error)

IsDirectory returns true if the given path refers to a directory

func (*Simple) IsFile

func (b *Simple) IsFile(ctx context.Context, path string) (bool, error)

IsFile returns true if the given path refers to a file

func (*Simple) IsLocal

func (b *Simple) IsLocal(ctx context.Context) (bool, error)

func (*Simple) ListDirectories

func (b *Simple) ListDirectories(ctx context.Context, path string) ([]string, error)

ListDirectories returns a list of directories rooted at a particular path

func (*Simple) ListExecutables

func (b *Simple) ListExecutables(ctx context.Context, path string) ([]string, error)

ListExecutables returns the executables in a particular directory as given by path

func (*Simple) PushFile

func (b *Simple) PushFile(ctx context.Context, sourcePath, destPath string) error

func (*Simple) RemoveFile

func (b *Simple) RemoveFile(ctx context.Context, path string) error

RemoveFile removes the given file from the device

func (*Simple) SetupLocalPort

func (b *Simple) SetupLocalPort(ctx context.Context, port int) (int, error)

SetupLocalPort makes sure that the given port can be accessed on localhost It returns a new port number to connect to on localhost

func (*Simple) Shell

func (b *Simple) Shell(name string, args ...string) shell.Cmd

Shell implements the Device interface returning commands that will error if run.

func (*Simple) Status

func (b *Simple) Status(ctx context.Context) Status

Status implements the Device interface returning the Status from the LastStatus field.

func (*Simple) String

func (b *Simple) String() string

func (*Simple) SupportsPerfetto

func (b *Simple) SupportsPerfetto(ctx context.Context) bool

SupportsPerfetto returns true if the given device supports taking a Perfetto trace.

func (*Simple) TempDir

func (b *Simple) TempDir(ctx context.Context) (string, app.Cleanup, error)

func (*Simple) TempFile

func (b *Simple) TempFile(ctx context.Context) (string, func(ctx context.Context), error)

TempFile creates a temporary file on the given Device. It returns the path to the file, and a function that can be called to clean it up.

func (*Simple) WriteFile

func (b *Simple) WriteFile(ctx context.Context, contents io.Reader, mode os.FileMode, destPath string) error