parl

package module
v0.4.27 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 26, 2022 License: ISC Imports: 21 Imported by: 14

README

Parl


A Go library for parallel programming of command-line utilities and system services

features: moderator, sqlite interface, package-selectable logging, debouncer, self-signed certificate authority, watchers, thread management, file system scan and operations, …


© 2018–present Harald Rudell (https://haraldrudell.github.io/haraldrudell/)
ISC License

“justice, peace and massive virtual parallelism”

How to use

import "github.com/haraldrudell/parl"

Documentation

Go Reference  Documentation in the Go Package Index

On March 16th, 2022, parl was open-sourced under an ISC License
Parl is about 15,000 lines of Go code with first line written on November 21, 2018

© 2018–present Harald Rudell harald.rudell@gmail.com (https://haraldrudell.github.io/haraldrudell/)

Documentation

Overview

Package parl handles inter-thread communication and controls parallelism

parl has sub-packages augmenting the Go standard library: 

perrors pfs plog pnet pos pruntime psql pstrings
psyscall pterm ptime

parl has feature packages: 

ev — handling of goroutine-based functions
goid — unique goroutine IDs
mains — functions for writing command-line utilities and services
parlca — self-signed certificate authority
progress — monitor work progress for a large number of threads
sqlite — local SQL database
threadprof — profiling and counters for what threads are doing
// statuser: thread hang detector
tracer — event lists by task rather than by time or thread

parl features per-writer thread-safe logging with topic and per-package output control:

Logging is to stderr except for the Out function. parl logging uses comma separator for numbers. One argument is output as string, two or more arguments is Printf. The location matched against the regular expression is full package path, optional type receiver and the funtion name: “github.com/haraldrudell/mypackage.(*MyType).MyFunc” 

Out(string, ...interface{}) — Standard output
Log(string, ...interface{}) — Always outputs to stderr
parl.D(string, ...interface{}) — Same as Log, intended for temporary use

Info(string, ...interface{}) — Informational progress messages
SetSilent(true) — removes Info output
IsSilent() — deteremines if Info printing applies

Debug(string, ...interface{}) — only prints for locations where SetDebug(true)
SetDebug(true) — Control Debug() globally, code location for all prints, long stack traces
SetRegexp(regExp string) (err error) — Regular expression controlling local Debug() printing
IsThisDebug() — Determines if debug is active for the executing function

Console(string, ...interface{}) — terminal interactivity output

parl.Recover() and parl.Recover2() thread recovery and mains.Executable.Recover() process recovery:

Threads can provide their errors via the perrors.ParlError thread-safe error store, plain error channels, parl.NBChan[error] or parl.ClosableChan[error]. parl.Recover and parl.Recover2 convert thread panic to error along with regular errors, annotating, retrieving and storing those errors and invoking error handling functions for them. mains.Recover is similar for the process. 

func thread(errCh *parl.NBChan[error]) { // real-time non-blocking error channel
  defer errCh.Close() // non-blocking close effective on send complete
  var err error
  defer parl.Recover2(parl.Annotation(), &err, errCh.Send)
  errCh.Ch() <- err // non-blocking
  if err = someFunc(); err != nil {
    err = perrors.Errorf("someFunc: %w", err) // labels and attaches a stack
    return
…
func myThreadSafeThread(wg *sync.WaitGroup, errs *perrors.ParlError) { // ParlError: thread-safe error store
  defer wg.Done()
  var err error
  defer parl.Recover(parl.Annotation(), &err, errs.AddErrorProc)
…

parl package features: 

AtomicBool — Thread-safe boolean
Closer — Deferrable, panic-free channel close
ClosableChan — Initialization-free channel with observable deferrable panic-free close
Moderator — A ticketing system for limited parallelism
NBChan — A non-blocking channel with trillion-size dynamic buffer
SerialDo — Serialization of invocations
WaitGroup —Observable WaitGroup
Debouncer — Invocation debouncer, pre-generics
Sprintf — Supporting thousands separator

Parl is about 15,000 lines of Go code with first line written on November 21, 2018

On March 16th, 2022, parl was open-sourced under an ISC License

© 2018–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/)

© 2020–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/) ISC License

Index

Constants

View Source 
const (
	Rfc3339s  = "2006-01-02 15:04:05Z07:00"
	Rfc3339ms = "2006-01-02 15:04:05.000Z07:00"
	Rfc3339us = "2006-01-02 15:04:05.000000Z07:00"
	Rfc3339ns = "2006-01-02 15:04:05.000000000Z07:00"
)

Variables

This section is empty.

Functions

func AddToPanic 

func AddToPanic(panicValue interface{}, additionalErr error) (err error)

AddToPanic takes a recover() value and adds it to additionalErr.

func Annotation 

func Annotation() (annotation string)

Annotation provides a default annotation [base package].[function]: "mypackage.MyFunc"

func Close added in v0.4.15 

func Close(closable io.Closer, errp *error)

func Closer added in v0.4.0 

func Closer[T any](ch chan T, errp *error)

Closer is a deferrable function that closes a channel recovering from panic

func CloserSend added in v0.4.15 

func CloserSend[T any](ch chan<- T, errp *error)

func Console 

func Console(format string, a ...interface{})

Console always print intended for command-line interactivity if debug is enabled, code location is appended

func Consolew added in v0.4.12 

func Consolew(format string, a ...interface{})

Consolew always print intended for command-line interactivity Consolew does not append a newline

func D 

func D(format string, a ...interface{})

D prints to stderr with code location Thread safe. D is meant for temporary output intended to be removed before check-in

func Debug 

func Debug(format string, a ...interface{})

Debug outputs only if debug is configured or the code location package matches regexp

func DoGoGetError added in v0.4.26 

func DoGoGetError(op func() (err error), g0 Go) (err error)

DoGoGetError executes op in a thread. err contains any error, error are not submitted to Go object. DoGoGetError blocks until the goroutine completes.

func DoProcThread added in v0.4.26 

func DoProcThread(op func(), g0 Go)

func DoThread added in v0.4.26 

func DoThread(op func() (err error), g0 Go)

DoThread is invoked in a go statement and executes op. g0 receives errors and is the wait-for function.

func DoThreadError added in v0.4.26 

func DoThreadError(op func() (err error), errCh chan<- error, g0 Go)

DoThreadError is a goroutine that returns its error separately.

func EnsureError 

func EnsureError(panicValue interface{}) (err error)

AddToPanic ensures that a recover() value is an error or nil.

func GetD added in v0.4.26 

func GetD(skipFrames int) (debug func(format string, a ...interface{}))

GetD obtains always printing D based on the invocation location for later execution

func GetDebug added in v0.4.25 

func GetDebug(skipFrames int) (debug func(format string, a ...interface{}))

GetDebug obtains a Debug based on the invocation location for later execution

func HandleErrp added in v0.2.2 

func HandleErrp(fn func(), errp *error)

HandleErrp recovers from a panic in fn storing at *errp. HandleErrp is deferable.

func HandlePanic 

func HandlePanic(fn func()) (err error)

HandlePanic recovers from panic in fn returning error.

func HandleParlError added in v0.2.2 

func HandleParlError(fn func(), storeError func(err error))

HandleParlError recovers from panic in fn invoking an error callback. HandleParlError is deferable storeError can be the thread-safe perrors.ParlError.AddErrorProc()

func Infallible added in v0.4.12 

func Infallible(err error)

func Info 

func Info(format string, a ...interface{})

Info prints unless silence has been configured with SetSilence(true) IsSilent deteremines the state of silence if debug is enabled, code location is appended

func IsSilent 

func IsSilent() (isSilent bool)

IsSilent if true it means that Info does not print

func IsThisDebug 

func IsThisDebug() bool

IsThisDebug returns whether debug logging is configured for the executing function

func IsThisDebugN added in v0.4.25 

func IsThisDebugN(skipFrames int) (isDebug bool)

func Log 

func Log(format string, a ...interface{})

Log invocations always print if debug is enabled, code location is appended

func Logw added in v0.4.12 

func Logw(format string, a ...interface{})

Logw invocations always print. Logw outputs withoput appending newline

func NewThreadResult added in v0.4.12 

func NewThreadResult(err error) (failure error)

func NoOnError added in v0.4.12 

func NoOnError(err error)

NoOnError is used with Recover to silence the default error logging

func OnCancel added in v0.4.12 

func OnCancel(fn func(), ctx context.Context)

OnCancel invokes fn when work done on behalf of context ctx should be canceled

func Out 

func Out(format string, a ...interface{})

Out prints extected output to stdout

func Outw added in v0.4.12 

func Outw(format string, a ...interface{})

func Recover 

func Recover(annotation string, errp *error, onError func(error))

Recover recovers from a panic invoking a function no more than once. If there is *errp does not hold an error and there is no panic, onError is not invoked. Otherwise, onError is invoked exactly once. *errp is updated with a possible panic.

func Recover2 

func Recover2(annotation string, errp *error, onError func(error))

Recover2 recovers from a panic and may invoke onError multiple times. onError is invoked if there is an error at *errp and on a possible panic. *errp is updated with a possible panic.

func SetDebug 

func SetDebug(debug bool)

if SetDebug is true, all Debug prints everywhere produce output. More selective debug printing can be achieved using SetInfoRegexp that matches package names.

func SetRegexp 

func SetRegexp(regExp string) (err error)

func SetSilent 

func SetSilent(silent bool)

SetSilent

func Short added in v0.4.26 

func Short(tim ...time.Time) (s string)

func ShortMs added in v0.4.27 

func ShortMs(tim ...time.Time) (s string)

func Sprintf added in v0.2.0 

func Sprintf(format string, a ...interface{}) string

Sprintf is a printer that supports comma in large numbers

Types

type AdbAdressProvider added in v0.4.0 

type AdbAdressProvider interface {
	// AdbSocketAddress retrievs the tcp socket address used
	// by a near Adbette implementation
	AdbSocketAddress() (socketAddress AdbSocketAddress)
}

AdressProvider retrieves the address from an adb server or device so that custom devices can be created

type AdbRequest added in v0.3.0 

type AdbRequest string

AdbRequest is a string formatted as an adb request. AdbRequest is only required for implementations using the Adbette protocol impementation

type AdbResponseID added in v0.4.0 

type AdbResponseID string

type AdbSocketAddress added in v0.4.0 

type AdbSocketAddress string

AdbSocketAddress is a tcp socket address accessible to the local host. The format is two parts separated by a colon. The first part is an IP address or hostname. The second part is a numeric port number. The empty string "" represents "localhost:5037". If the port part is missing, such as "localhost" it implies port 5037. If the host part is missing, it implies "localhost". Note that locahost is valid both for IPv4 and IPv6.

type AdbSyncRequest added in v0.4.0 

type AdbSyncRequest string

type Adbette added in v0.3.0 

type Adbette interface {
	// SendReadOkay sends a request to a remote adb endpoint.
	// if anything else than OKAY is received back from the
	// remote endpoint, err is non-nil.
	SendReadOkay(request AdbRequest) (err error)
	// ReadString reads utf-8 text up to 64 KiB-1 in length
	ReadString() (s string, err error)
	// ConnectToDevice sends a forwarding request to an adb
	// server to connect to one of its devices
	ConnectToDevice(serial AndroidSerial) (err error)
	// Shell executes a shell command on a device connected to the adb server.
	// out is a combination of stderr and stdout.
	// The status code from an on-device command cannot be obtained
	Shell(command string, reader ...func(conn io.ReadWriteCloser) (err error)) (out string, err error)
	// TrackDevices orders a server to emit serial number as they become available
	TrackDevices() (err error)
	// Devices lists the currently online serials
	Devices() (serials []AndroidSerial, err error)
	// DeviceStati returns all available serials and their status
	// The two slices correspond and are of the same length
	DeviceStati() (serials []AndroidSerial, stati []AndroidStatus, err error)
	// Closer closes an adb connection, meant to be a deferred function
	Closer(errp *error)
	// SetSync sets the protocol mode of an adb device connection to sync
	SetSync() (err error)
	// LIST is a sync request that lists file system entries in a directory of an adb device
	LIST(remoteDir string, dentReceiver func(mode uint32, size uint32, time uint32, byts []byte) (err error)) (err error)
	// RECV fetches the contents of a file on an adb device
	RECV(remotePath string, blobReceiver func(data []byte) (err error)) (err error)
	// CancelError is a value that a LIST or RECV callback routines can return to
	// cancel further invocations
	CancelError() (cancelError error)

	SendBlob(syncRequest AdbSyncRequest, data []byte) (err error)
	ReadBlob() (byts []byte, err error)
	ReadResponseID() (responseID AdbResponseID, err error)
	ReadBytes(byts []byte) (err error)
	SendBytes(byts []byte) (err error)
}

Adbette is a minimal implementation of the adb Android debug bridge protocol. Adbette include both adb server and Android device functions. Adbette is extensible in that additional protocol features are easily implemented without concern for protocol details. to shutdown an Adbette and release its resouces, invoke the Closer method

type Adbetter added in v0.3.0 

type Adbetter interface {
	NewConnection(address AdbSocketAddress, ctx context.Context) (conn Adbette, err error)
}

Adbetter is a factory instance for connections featuring Adbette context is used for terminating a connection attempt. context is not retained in the connection.

type AndroidSerial added in v0.3.0 

type AndroidSerial string

AndroidSerial uniquely identities an Android device. It is typically a string of a dozen or so 8-bit chanacters consisting of lower and upper case a-zA-Z0-9

type AndroidStatus added in v0.3.0 

type AndroidStatus string

AndroidStatus indicates the current status of a device known to a Server or Serverette it is a single word of ANSII-set characters 

const AndroidOnline AndroidStatus = "device"

AndroidOnline is the Android device status that indicates an online device

type AtomicBool 

type AtomicBool struct {
	// contains filtered or unexported fields
}

AtomicBool is a thread-safe flag. AtomicBool requires no initialization 

var isDone parl.AtomicBool
if isDone.Set() // isDone was not set, but is set now
…
if !isDone.IsTrue() // isDone is not set

func (*AtomicBool) Clear 

func (ab *AtomicBool) Clear() (wasSet bool)

func (*AtomicBool) IsTrue 

func (ab *AtomicBool) IsTrue() (isTrue bool)

func (*AtomicBool) Set 

func (ab *AtomicBool) Set() (wasNotSet bool)

type CancelAndContext added in v0.4.20 

type CancelAndContext struct {
	// contains filtered or unexported fields
}

func NewCancelAndContext added in v0.4.20 

func NewCancelAndContext(ctx context.Context) (cc *CancelAndContext)

func (*CancelAndContext) Cancel added in v0.4.20 

func (cc *CancelAndContext) Cancel()

func (*CancelAndContext) Context added in v0.4.20 

func (cc *CancelAndContext) Context() (ctx context.Context)

type CancelContext added in v0.4.12 

type CancelContext interface {
	context.Context
	Cancel()
	CancelOnError(errp *error)
}

context.WithCancel provides a thread-safe race-free idempotent many-to-many shutdown relation.

func NewCancelContext added in v0.4.12 

func NewCancelContext(ctx context.Context) (cancelCtx CancelContext)

NewCancelContext instantiates parl.CancelContext, a context with Cancel exposed as a method

func NewCancelContextFunc added in v0.4.26 

func NewCancelContextFunc(ctx context.Context, cancel context.CancelFunc) (cancelCtx CancelContext)

type CancelContextDo added in v0.4.12 

type CancelContextDo struct {
	context.Context
	// contains filtered or unexported fields
}

CancelContextDo implements parl.CancelContext. CancelContextDo is a context with a thread-safe, race-free, idempotent Cancel method

func (*CancelContextDo) Cancel added in v0.4.12 

func (cc *CancelContextDo) Cancel()

Cancel cancels this context

func (*CancelContextDo) CancelOnError added in v0.4.26 

func (cc *CancelContextDo) CancelOnError(errp *error)

type Certificate added in v0.4.26 

type Certificate interface {
	DER() (der CertificateDer)
	PEM() (pemBytes PemBytes)
	ParseCertificate() (certificate *x509.Certificate, err error)
}

type CertificateAuthority added in v0.4.26 

type CertificateAuthority interface {
	Check() (cert *x509.Certificate, err error) // gets x509.Certificate version
	DER() (certificateDer CertificateDer)       // untyped bytes, der: Distinguished Encoding Rules binary format
	Sign(template *x509.Certificate, publicKey crypto.PublicKey) (certDER CertificateDer, err error)
	PEM() (pemBytes PemBytes)
	Private() (privateKey PrivateKey)
}

type CertificateDer added in v0.4.26 

type CertificateDer []byte

CertificateDer is a binary encoding of a certificate. der: Distinguished Encoding Rules is a binary format based on asn1.

type ClosableChan added in v0.4.0 

type ClosableChan[T any] struct {
	// contains filtered or unexported fields
}

ClosableChan wraps channel close. ClosableChan is an initialization-free channel with a deferable, thread-safe, idempotent and observable Close method. Close closes the channel exactly once, recovering panics. IsClosed provides wether the Close method did execute close. 

var errCh parl.ClosableChan[error]
go thread(&errCh)
err, ok := <-errCh.Ch()
if errCh.isClosed() { // can be inspected
…
func thread(errCh *parl.ClosableChan[error]) {
  defer errCh.Close(nil) // will not terminate the process
  errCh.Ch() <- err

func NewClosableChan added in v0.4.5 

func NewClosableChan[T any](ch ...chan T) (cl *ClosableChan[T])

NewClosableChan ensures a chan does not throw

func (*ClosableChan[T]) Ch added in v0.4.0 

func (cl *ClosableChan[T]) Ch() (ch chan T)

Ch retrieves the channel

func (*ClosableChan[T]) Close added in v0.4.0 

func (cl *ClosableChan[T]) Close(errp ...*error) (didClose bool, err error)

Close ensures the channel is closed. Close does not panic. Close is thread-safe. Close does not return until the channel is closed. Upon return, all invocations have a possible close error in err. if errp is non-nil, it is updated with a possible error didClose indicates whether this invocation closed the channel

func (*ClosableChan[T]) IsClosed added in v0.4.0 

func (cl *ClosableChan[T]) IsClosed() (isClosed bool)

IsClosed indicates whether the Close method has been invoked

type Closers added in v0.4.26 

type Closers struct {
	// contains filtered or unexported fields
}

Closers collects io.Closer objects so they can be closed all at once. Closer is required for servers that may have the server itself and

func (*Closers) Add added in v0.4.26 

func (cl *Closers) Add(closer io.Closer)

func (*Closers) Close added in v0.4.26 

func (cl *Closers) Close() (err error)

func (*Closers) EnsureClosed added in v0.4.26 

func (cl *Closers) EnsureClosed(closer io.Closer) (err error)

func (*Closers) Remove added in v0.4.26 

func (cl *Closers) Remove(closer io.Closer) (ok bool)

type Conduit added in v0.4.12 

type Conduit[T any] interface {
	Sender[T]
	Receiver[T]
}

func NewConduit added in v0.4.12 

func NewConduit[T any](done Doneable, ctx context.Context) (conduit Conduit[T])

type ConduitDo added in v0.4.12 

type ConduitDo[T any] struct {
	// contains filtered or unexported fields
}

func (*ConduitDo[T]) Count added in v0.4.12 

func (ct *ConduitDo[T]) Count() (count int)

func (*ConduitDo[T]) Get added in v0.4.12 

func (ct *ConduitDo[T]) Get() (value T, ok bool)

func (*ConduitDo[T]) GetSlice added in v0.4.12 

func (ct *ConduitDo[T]) GetSlice(max int) (values []T, ok bool)

func (*ConduitDo[T]) IsCanceled added in v0.4.12 

func (ct *ConduitDo[T]) IsCanceled() (IsCanceled bool)

func (*ConduitDo[T]) IsEmpty added in v0.4.12 

func (ct *ConduitDo[T]) IsEmpty() (isEmpty bool)

func (*ConduitDo[T]) Put added in v0.4.12 

func (ct *ConduitDo[T]) Put(value T) (IsCanceled bool)

func (*ConduitDo[T]) PutSlice added in v0.4.12 

func (ct *ConduitDo[T]) PutSlice(values []T) (IsCanceled bool)

func (*ConduitDo[T]) WaitCount added in v0.4.12 

func (ct *ConduitDo[T]) WaitCount() (waitCount int)

type Counter added in v0.3.0 

type Counter interface {
	Inc() (counter Counter)
	Dec() (counter Counter)
	SetValue(value uint64)
	CounterValue(reset bool) (values CounterValues)
}

type CounterID added in v0.3.0 

type CounterID string

type CounterValues added in v0.3.0 

type CounterValues interface {
	Get() (value uint64, running uint64, max uint64, incRate uint64, decRate uint64)
	Value() (value uint64)
	Running() (running uint64)
	Max() (max uint64)
	IncRate() (incRate uint64)
	DecRate() (decRate uint64)
}

type Counters added in v0.3.0 

type Counters interface {
	GetOrCreateCounter(name CounterID) (counter Counter)
	GetCounters() (orderedKeys []CounterID, m map[CounterID]Counter)
	ResetCounters()
}

Counters are extremely useful to determine that your code abide by intended paralellism and identifying hangs or abnormalisms. Printing counters every second can verify adequate progress and possibly identify blocking of threads or swapping and garbage collection outages. Inc increases two counters while Dec decreases one, enabling tracking both number of invocations as well as how many remain running by doing Inc and a deferred Dec.

type CountersFactory added in v0.3.0 

type CountersFactory interface {
	NewCounters(useCounters bool) (counters Counters)
}

type DB added in v0.4.12 

type DB interface {
	Exec(partition DBPartition, query string, ctx context.Context,
		args ...any) (execResult ExecResult, err error)
	Query(partition DBPartition, query string, ctx context.Context,
		args ...any) (sqlRows *sql.Rows, err error)
	QueryRow(partition DBPartition, query string, ctx context.Context,
		args ...any) (sqlRow *sql.Row, err error)
	QueryString(partition DBPartition, query string, ctx context.Context,
		args ...any) (value string, err error)
	QueryInt(partition DBPartition, query string, ctx context.Context,
		args ...any) (value int, err error)
	Close() (err error)
}

type DBFactory added in v0.4.12 

type DBFactory interface {
	NewDB(
		dsnr DataSourceNamer,
		schema func(dataSource DataSource, ctx context.Context) (err error)) (db DB)
}

DBFactory is a standardized way to obtain DB objects

type DBPartition added in v0.4.14 

type DBPartition string

type DSNrFactory added in v0.4.14 

type DSNrFactory interface {
	NewDSNr(appName string) (dsnr DataSourceNamer)
}

type DataSource added in v0.4.12 

type DataSource interface {
	PrepareContext(ctx context.Context, query string) (stmt *sql.Stmt, err error)
	Close() (err error)
}

type DataSourceNamer added in v0.4.12 

type DataSourceNamer interface {
	DSN(partition ...DBPartition) (dataSourceName string)
	DataSource(dsn string) (dataSource DataSource, err error)
}

type Debouncer added in v0.4.26 

type Debouncer[T any] struct {
	// contains filtered or unexported fields
}

func NewDebouncer 

func NewDebouncer[T any](d time.Duration, in <-chan T,
	sender func([]T),
	errFn func(err error), ctx context.Context) (db *Debouncer[T])

Debouncer debounces event stream values. sender and errFb functions must be thread-safe. Debouncer is shutdown by in channel close or via context.

func (*Debouncer[T]) Wait added in v0.4.26 

func (db *Debouncer[T]) Wait()

type Dent added in v0.3.0 

type Dent interface {
	// Name is utf-8 base path in device file system.
	// Name is base name, ie. file name and extension.
	Name() (name string)
	// Modified time, the time file contents was changed, second precision, continuous time
	Modified() (modified time.Time)
	// IsDir indicates directory.
	// LIST only support symbolic link, directory and regular file types
	IsDir() (isDir bool)
	// IsRegular indicates regular file, ie. not a directory or symbolic link.
	// LIST only support symbolic link, directory and regular file types
	IsRegular() (isRegular bool) // ie.not directory or symlink
	// Perm returns os.FileMode data.
	// 9-bit Unix permissions per os.FilePerm.
	// LIST also supports directory and symlink bits
	Perm() (perm fs.FileMode)
	// Size is limited to 4 GiB-1
	Size() (size uint32)
}

Dent is the information returned by adb ls or LIST

type Devicette added in v0.3.0 

type Devicette interface {
	// Serial returns the serial number for this device
	Serial() (serial AndroidSerial)
	// Shell executes a shell command on the device.
	// The resulting socket can be obtained either using the reader callback,
	// which is a socket connection to the device,
	// or by collecting the out string.
	Shell(command string, reader func(conn io.ReadWriteCloser) (err error)) (out string, err error)
	/*
		Pull copies a remote file or directory on the Android device to a local file system location.
		the local file must not exist.
		Pull refuses certain files like product apks. shell cat works
	*/
	Pull(remotePath, nearPath string) (err error)
	/*
		List has some peculiarities:
		If remoteDir is not an existing directory, an empty list is returned.
		Entries with insufficient permisions are ignored.
		Update: . and .. are removed, adb LIST ortherwise do return those.
		File mode: the only present type bits beyond 9-bit Unix permissions are
		symlink, regular file and directory.
		File size is limited to 4 GiB-1.
		Modification time resolution is second and range is confined to a 32-bit Unix timestamp.
	*/
	List(remoteDir string) (dFileInfo []Dent, err error)
}

Devicette is a generic implementation of the capabilities of a device implementing the adb Android debug bridge protocol

type DevicetteFactory added in v0.4.0 

type DevicetteFactory interface {
	// NewDevicette creates a Devicette interacting with remote adb Android Debug Bridge
	// devices via an adb server available at the socket address address
	NewDevicette(address AdbSocketAddress, serial AndroidSerial, ctx context.Context) (devicette Devicette)
}

DevicetteFactory describes how Devicette objects are obtained.

type DoErr added in v0.4.26 

type DoErr interface {
	DoErr(op func() (err error)) (err error)
}

type Doneable added in v0.4.12 

type Doneable interface {
	Add(delta int)
	Done()
}

Doneable is the callee part of sync.Waitgroup and other implementations Doneable is a many-to-many relation. Doneable allows the callee to instatiate and invoke any number of things that are awaitable by the caller. 

… = NewSomething(&waitsForLots, &shutsDownLots)
go someThread(&waitsForLots, &shutsDownLots)
func someThread(Doneable w, context.Context ctx) {
  defer w.Done()
  w.Add(2)
  go somethingElse()

func EnsureDoneable added in v0.4.12 

func EnsureDoneable(done Doneable) (done2 Doneable)

type DoneableNil added in v0.4.12 

type DoneableNil struct{}

func (*DoneableNil) Add added in v0.4.12 

func (de *DoneableNil) Add(delta int)

func (*DoneableNil) Done added in v0.4.12 

func (de *DoneableNil) Done()

type Err added in v0.4.12 

type Err interface {
	error
}

Err is a public error

type ErrorCloser added in v0.4.20 

type ErrorCloser interface {
	InvokeIfError(addError func(err error))
	Close()
}

type ErrorConduit added in v0.4.12 

type ErrorConduit uint8
const (
	// EcSharedChan emits error on a shared error channel of the GoCreator object
	EcSharedChan ErrorConduit = iota + 1
	// EcErrChan emits error on an individual channel of the Goer object
	EcErrChan
)

type ErrorManager added in v0.4.20 

type ErrorManager interface {
	Ch() (ch <-chan GoError)
}

type ErrorSink added in v0.4.20 

type ErrorSink interface {
	AddError(err error)
}

type ExecResult added in v0.4.14 

type ExecResult interface {
	Get() (ID int64, rows int64)
	String() (s string)
}

type ExitAction added in v0.4.12 

type ExitAction uint8
const (
	// ExCancelOnExit cancels the GoCreator context ie. all actions on behalf of the
	// GoCreator if the goroutine exits
	ExCancelOnExit ExitAction = iota + 1
	// ExIgnoreExit takes no action on goruotine exit
	ExIgnoreExit
	// ExCancelOnFailure cancels the GoCreator context ie. all actions on behalf of the
	// GoCreator if the goroutine exits with error
	ExCancelOnFailure
)

type FSLocation 

type FSLocation interface {
	Directory() (directory string)
}

type FanOut 

type FanOut struct {
	ErrCh   chan error
	Results chan interface{}
	// contains filtered or unexported fields
}

func NewFanOut 

func NewFanOut() (fo *FanOut)

func (*FanOut) Do 

func (cr *FanOut) Do(name string, proc FanProc)

Do executes a procedure in a goroutine that has no result other than a possible non-nil error

func (*FanOut) Run 

func (cr *FanOut) Run(name string, thunk FanThunk)

Run executes a thunk in a goroutine with a possible non-nil result and a possible non-nil error

func (*FanOut) Wait 

func (cr *FanOut) Wait()

Wait waits for all Do and Run invocations to complete, then shuts down

type FanProc 

type FanProc func() (err error)

type FanThunk 

type FanThunk func() (result interface{}, err error)

type Frame added in v0.4.20 

type Frame interface {
	Loc() (location *pruntime.CodeLocation)
	Args() (args string)
	String() (s string)
}

type Future added in v0.4.26 

type Future[T any] struct {
	// contains filtered or unexported fields
}

func NewFuture added in v0.4.26 

func NewFuture[T any](fn func() (value T, err error)) (future *Future[T])

NewFuture computes a future value in a separate goroutine. fn must be thread-safe. an fn panic is recovered. Result is either via Wait() or received from a channel from Ch().

func (*Future[T]) Ch added in v0.4.26 

func (f *Future[T]) Ch() (ch <-chan FutureValue[T])

func (*Future[T]) IsDone added in v0.4.26 

func (f *Future[T]) IsDone() (isDone bool)

func (*Future[T]) Wait added in v0.4.26 

func (f *Future[T]) Wait() (value T, err error)

type FutureCore added in v0.4.26 

type FutureCore[T any] struct {
	// contains filtered or unexported fields
}

func InitFutureCore added in v0.4.26 

func InitFutureCore[T any](fn func() (value T, err error), f *FutureCore[T]) (futureCore *FutureCore[T])

func NewFutureCore added in v0.4.26 

func NewFutureCore[T any](fn func() (value T, err error)) (futureCore *FutureCore[T])

func (*FutureCore[T]) IsDone added in v0.4.26 

func (f *FutureCore[T]) IsDone() (isDone bool)

func (*FutureCore[T]) Wait added in v0.4.26 

func (f *FutureCore[T]) Wait() (value T, err error)

type FutureValue added in v0.4.26 

type FutureValue[T any] struct {
	// contains filtered or unexported fields
}

type Go added in v0.4.12 

type Go interface {
	// Register performs no function but allows the Go object to collect
	// information on the new thread
	Register()
	// Add allows for a goroutine to have the caller wait for
	// additional internal goroutines.
	Add(delta int)
	// AddError allows a goroutine to send non-fatal errors
	AddError(err error)
	// Done indicates that a goroutine has finished.
	// err nil typically means successful exit.
	// Done is deferrable.
	// If the waitGroup is not done, a GePreDoneExit status is sent.
	// If Done is for the final goroutine, GeExit is sent.
	Done(errp *error)
	// Cancel allows for the goroutine or its sub-threads to initiate local cancel
	Cancel()
	// Context will cancel when work done on behalf of this context
	// should be canceled
	Context() (ctx context.Context)
	// SubGo allows a sub-group of threads that can be canceled and waited for separately.
	// Subgo has access to the AddError error sink.
	// Subgo has its own sub-context and waitgroup.
	// Subgo Add and Done are duplicated.
	SubGo(local ...GoSubLocal) (subGo SubGo)
}

Go offers all-in-one functions for a single go statement initiating goroutine execution. 

AddError sends non-fatal errors ocurring during goroutine execution.
Done allows to provide outcome and for callers to wait for the goroutine.
Add allows for additional sub-threads
Context provide a Done channel and Err to determine if the goroutine should cancel.
SubGo allows for sub-threads with separate cancelation and wait

type GoError added in v0.4.12 

type GoError interface {
	error // Error() string
	// GetError retrieves the original error value
	GetError() (err error)
	// Source describes the source and significance of the error
	Source() (source GoErrorSource)
	// Goer provides the Goer object associated with the goroutine
	// causing the error
	Goer() (goer Goer)
	String() (s string)
}

GoError is an error or a thread exit associated with a goroutine Goer returns the Goer object handling the goroutine that originated the error

type GoErrorSource added in v0.4.12 

type GoErrorSource uint8
const (
	// GeNonFatal indicates a non-fatal error ocurring during processing.
	// err is non-nil
	GeNonFatal GoErrorSource = iota + 1
	// GePreDoneExit indicates an exit value of a subordinate goroutine,
	// other than the final exit of the last running goroutine.
	// err may be nil
	GePreDoneExit
	// GeExit indicates exit of the last goroutine.
	// err may be nil.
	// The error channel may close after GeExit.
	GeExit
)

func (GoErrorSource) String added in v0.4.17 

func (ge GoErrorSource) String() (s string)

type GoGroup added in v0.4.18 

type GoGroup interface {
	// Add indicates a new goroutine about to be launched.
	// conduit indicates how errors will be propagated from
	// the goroutine.
	// exitAction describes what actions the GoCreator object
	// will take upon goroutine exit
	Add(conduit ErrorConduit, exitAction ExitAction) (goer Goer)
	// WaitPeriod waits for all goroutines managed by this GoCreator
	// to exit, periodically printing a description of the goroutines
	// that have yet to exit
	WaitPeriod(duration ...time.Duration)
	GoManager
}

GoGroup manages any number of go statements. Exit action and error routing is configurable per go statement. Each go statement can send errors, receive cancel, initiate cancel and be waited on. The GoGroup and each go statement are cancelable. The GoGroup and each go statement can be waited on.

type GoGroupFactory added in v0.4.19 

type GoGroupFactory interface {
	NewGoGroup(ctx context.Context) (goGroup GoGroup)
}

type GoIndex added in v0.4.12 

type GoIndex int

type GoManager added in v0.4.20 

type GoManager interface {
	// Ch is a channel that will close once all go statements have exited.
	// If the Goer was obtained from a GoGroup, Ch only emits data for EcErrChan.
	// Ch emits errors and exit results as they occur.
	Ch() (ch <-chan GoError)
	// IsExit indicates whether all go statements and Go.Add incovations
	// has exited.
	IsExit() (isExit bool)
	// Wait waits for all go statements and Go.Add invocations
	Wait()
	// Cancel indicates to all threads managed by this Goer that
	// work done on behalf of this context should be canceled
	Cancel()
	// Context will cancel when work done on behalf of this context
	// should be canceled
	Context() (ctx context.Context)
	String() (s string)
}

type GoSubLocal added in v0.4.26 

type GoSubLocal string
const (
	GoSubIsLocal GoSubLocal = "local"
)

type Goer added in v0.4.12 

type Goer interface {
	// Go returns a Go object to be provided to a go statement.
	// A Goer obained from GoGroup is only intended to manage one go statement.
	Go() (g0 Go)
	// AddError emits a GeNonFatal error on the error channel
	AddError(err error)
	GoManager
}

Goer manages one or more go statements. Goer is obtained from a GoGroup to manage a single go statement or from a GoerFactory to manage any number of go statements uniformly or from a GoError. The managed go statements can send errors, receive cancel, initiate cancel and be waited on. Cancel and Wait are separate for the Goer and only pertains to the managed go statements. The wait mechanic used is observable.

type GoerFactory added in v0.4.18 

type GoerFactory interface {
	NewGoer(ctx context.Context) (goer Goer)
}

type Moderator 

type Moderator struct {
	// contains filtered or unexported fields
}

Moderator invokes functions at a limited level of parallelism. It is a ticketing system 

m := NewModerator(20, ctx)
m.Do(func() (err error) { // waiting here for a ticket
  // got a ticket!
  …
  return or panic // ticket automatically returned
m.String() → waiting: 2(20)

func NewModerator 

func NewModerator(parallelism uint64, ctx context.Context) (mo *Moderator)

NewModerator creates a cancelable Moderator used to limit parallelism

func NewModeratorFromCore added in v0.4.26 

func NewModeratorFromCore(mc *ModeratorCore, ctx context.Context) (mo *Moderator)

NewModeratorFromCore allows multiple cancelable Moderators to share a ModeratorCore ticket pool

func (*Moderator) Do 

func (mo *Moderator) Do(fn func())

Do calls fn limited by the moderator’s parallelism. If the moderator is shut down, ErrModeratorShutdown is returned

func (*Moderator) DoErr added in v0.4.26 

func (mo *Moderator) DoErr(fn func() error) (err error)

func (*Moderator) Status 

func (mo *Moderator) Status() (parallelism uint64, active uint64, waiting uint64, isShutdown bool)

func (*Moderator) String 

func (mo *Moderator) String() (s string)

type ModeratorCore added in v0.4.26 

type ModeratorCore struct {
	// contains filtered or unexported fields
}

ModeratorCore invokes functions at a limited level of parallelism. ModeratorCore is a ticketing system. ModeratorCore does not have a cancel feature. 

m := NewModeratorCore(20, ctx)
m.Do(func() (err error) { // waiting here for a ticket
  // got a ticket!
  …
  return or panic // ticket automatically returned
m.String() → waiting: 2(20)

func NewModeratorCore added in v0.4.26 

func NewModeratorCore(parallelism uint64) (mo *ModeratorCore)

NewModerator creates a new Moderator used to limit parallelism

func (*ModeratorCore) Do added in v0.4.26 

func (mo *ModeratorCore) Do(fn func())

Do calls fn limited by the moderator’s parallelism. Do blocks until a ticket is available Do uses the same thread.

func (*ModeratorCore) Status added in v0.4.26 

func (mo *ModeratorCore) Status() (parallelism uint64, active uint64, waiting uint64)

func (*ModeratorCore) String added in v0.4.26 

func (mo *ModeratorCore) String() (s string)

type NBChan added in v0.4.0 

type NBChan[T any] struct {
	perrors.ParlError // thread panics
	// contains filtered or unexported fields
}

NBChan is a non-blocking send channel with trillion-size buffer. NBChan can be used as an error channel where the thread does not block from a delayed or missing reader. NBChan is initialization-free, thread-safe, idempotent, deferrable and observable. Ch(), Send(), Close() CloseNow() IsClosed() Count() are not blocked by channel send and are panic-free. Close() CloseNow() are deferrable. WaitForClose() waits until the underlying channel has been closed. NBChan implements a thread-safe error store perrors.ParlError. NBChan.GetError() returns thread panics and close errors. No errors are added to the error store after the channel has closed. NBChan does not generate errors. When it does, errors are thread panics and close errors. 

var errCh parl.NBChan[error]
go thread(&errCh)
err, ok := <-errCh.Ch()
errCh.WaitForClose()
errCh.GetError()
…
func thread(errCh *parl.NBChan[error]) {
  defer errCh.Close() // non-blocking close effective on send complete
  var err error
  defer parl.Recover(parl.Annotation(), &err, errCh.AddErrorProc)
  errCh.Ch() <- err // non-blocking
  if err = someFunc(); err != nil {
    err = perrors.Errorf("someFunc: %w", err)
    return

func NewNBChan added in v0.4.0 

func NewNBChan[T any](ch ...chan T) (nbChan *NBChan[T])

NewNBChan instantiates a non-blocking trillion-size buffer channel. NewNBChan allows initialization based on an existing channel. NewNBChan does not need initialization and can be used like: 

var nbChan NBChan[error]
go thread(&nbChan)

func (*NBChan[T]) Ch added in v0.4.0 

func (nb *NBChan[T]) Ch() (ch chan T)

Ch obtains the channel

func (*NBChan[T]) Close added in v0.4.0 

func (nb *NBChan[T]) Close() (didClose bool)

Close orders the channel to close once pending sends complete. Close is thread-safe, non-blocking and panic-free.

func (*NBChan[T]) CloseNow added in v0.4.5 

func (nb *NBChan[T]) CloseNow(errp ...*error) (err error, didClose bool)

CloseNow closes without waiting for sends to complete. Close does not panic. Close is thread-safe. Close does not return until the channel is closed. Upon return, all invocations have a possible close error in err. if errp is non-nil, it is updated with error status

func (*NBChan[T]) Count added in v0.4.0 

func (nb *NBChan[T]) Count() (unsentCount int)

Count returns number of unsent values

func (*NBChan[T]) DidClose added in v0.4.20 

func (nb *NBChan[T]) DidClose() (didClose bool)

func (*NBChan[T]) IsClosed added in v0.4.0 

func (nb *NBChan[T]) IsClosed() (isClosed bool)

func (*NBChan[T]) Send added in v0.4.0 

func (nb *NBChan[T]) Send(value T)

Send sends non-blocking on the channel

func (*NBChan[T]) WaitForClose added in v0.4.5 

func (nb *NBChan[T]) WaitForClose()

type Once added in v0.4.18 

type Once struct {
	// contains filtered or unexported fields
}

parl.Once is an observable sync.Once parl.Once is thread-safe and does not require initialization No thread will return from Once.Do until once.Do has completed

func (*Once) Do added in v0.4.18 

func (o *Once) Do(f func())

func (*Once) IsDone added in v0.4.18 

func (o *Once) IsDone() (isDone bool)

type OrderedMap added in v0.4.26 

type OrderedMap[K constraints.Ordered, V any] interface {
	Get(key K, newV func() (value *V), makeV func() (value V)) (value V)
	Has(key K) (value V, ok bool)
	Delete(key K)
	List() (list []V)
}

OrderedMap stores an ordered list of values accessible in constant time O(1). The map can be ordered by key value or by a custom key order. For large-sized structs, V can be pointer. Key must be constraints.Ordered, ie. not slice map or func or more. 

pslices.NewOrderedMap
psclies.NewOrderedMapFunc

type OrderedMapAny added in v0.4.26 

type OrderedMapAny[O any, K constraints.Ordered, V any] interface {
	Get(key O, newV func() (value *V), makeV func() (value V)) (value V)
	Has(order O) (value V, ok bool)
	Delete(order O)
	List() (list []V)
}

OrderedMap stores an ordered list of values accessible in constant time O(1). The map is in custom key order. For large-sized structs, V can be pointer. A function converts O to K 

pslices.NewOrderedMapAny

type OrderedPointers added in v0.4.26 

type OrderedPointers[E any] interface {
	Insert(element *E)
	List() (list []*E)
}

OrderedPointers[E any] is an ordered list of pointers sorted by the referenced values. OrderedPointers should be used when E is a large struct. pslices.NewOrderedPointers[E constraints.Ordered]() instantiates for pointers to comparable types, ie. not func slice map. pslices.NewOrderedAny instantiates for pointers to any type or for custom sort orders.

type OrderedValues added in v0.4.26 

type OrderedValues[E any] interface {
	Insert(element E)
	Delete(element E)
	List() (list []E)
}

OrderedValues[E any] is an ordered list of values sorted by value. OrderedValues should be used when E is an interface or a small-sized value. pslices.NewOrderedValues[E constraints.Ordered]() instantiates for comparable types, ie. not func map slice. pslices.NewOrderedAny[E any](cmp func(a, b E) (result int)) instantiates for any type or for custom sort order.

type Password 

type Password interface {
	HasPassword() (hasPassword bool)
	Password() (password string)
}

type PemBytes added in v0.4.26 

type PemBytes []byte

PemBytes bytes is 7-bit ascii string representing keys or certificates

type Periodically added in v0.4.16 

type Periodically struct {
	// contains filtered or unexported fields
}

func NewPeriodically added in v0.4.16 

func NewPeriodically(fn func(t time.Time), ctx context.Context, period ...time.Duration) (periodically *Periodically)

func (*Periodically) Wait added in v0.4.26 

func (p *Periodically) Wait()

type PrivateKey added in v0.4.26 

type PrivateKey interface {
	crypto.Signer                                  // Public() Sign()
	DER() (privateKeyDer PrivateKeyDer, err error) // untyped key material, both private and public keys
	DERe() (privateKeyDer PrivateKeyDer)
	PEM() (pemBytes PemBytes, err error)
	PEMe() (pemBytes PemBytes)
	PublicKey() (publicKey PublicKey)
	Algo() (algo x509.PublicKeyAlgorithm)
	// validate ensures the private key is present, modeled after rsa.Validate
	Validate() (err error)
}

PrivateKey implements crypto.Signer and can therefore be used as tls.Certificate.PrivateKey

type PrivateKeyDer added in v0.4.26 

type PrivateKeyDer []byte

PublicKeyDer is a binary encoding of a private and public key-pair

type PrivateKeyFactory added in v0.4.26 

type PrivateKeyFactory interface {
	NewPrivateKey(algo x509.PublicKeyAlgorithm) (privateKey PrivateKey, err error)
}

type PublicKey added in v0.4.26 

type PublicKey interface {
	DER() (publicKeyDer PublicKeyDer, err error)
	DERe() (publicKeyDer PublicKeyDer)
	PEM() (pemBytes PemBytes, err error)
	PEMe() (pemBytes PemBytes)
	Equal(x crypto.PublicKey) (isEqual bool)
	Algo() (algo x509.PublicKeyAlgorithm)
}

PublicKey contains a public key extracted from a KeyPair

type PublicKeyDer added in v0.4.26 

type PublicKeyDer []byte

PublicKeyDer is a binary encoding of a public key

type Receiver added in v0.4.12 

type Receiver[T any] interface {
	// Get receives one element from the conduit.
	// ok is true if Get did receive a valid element.
	// Get blocks if no element is available.
	// Get returns the zero-value of T and ok false if the coundit
	// is closed and empty.
	Get() (value T, ok bool)
	// GetSlice receives one or more elements from the conduit.
	// ok is true if GetSlice did receive valid elements.
	// GetSlice blocks if no elements are available.
	// GetSlice returns the zero-value of T and ok false if the coundit
	// is closed and empty.
	GetSlice(max int) (values []T, ok bool)
	// IsCanceled determines if the conduit has been canceled.
	// The conudit may still have data elements.
	IsCanceled() (IsCanceled bool)
	// IsEmpty determines if the conduit is empty
	IsEmpty() (isEmpty bool)
	// Count retrieves how many data elements are waiting in the counduit
	Count() (count int)
	// WaitCount retrieves how many conduit receive invocations are waiting for data
	WaitCount() (waitCount int)
}

type Sender added in v0.4.12 

type Sender[T any] interface {
	// Put is thread-safe, non-blocking, panic-free.
	Put(value T) (IsCanceled bool)
	// PutSlice is thread-safe, non-blocking, panic-free.
	// PutSlice(nil) determines if the counduit is canceled.
	PutSlice(values []T) (IsCanceled bool)
}

type SerialDo 

type SerialDo struct {
	// contains filtered or unexported fields
}

SerialDo serializes a thunk.

func NewSerialDo 

func NewSerialDo(
	thunk func(at time.Time),
	eventFn func(event *SerialDoEvent),
	errFn func(err error),
	ctx context.Context) (sdo *SerialDo)

NewSerialDo serializes .Do invocations eventFn must be thread-safe. errFn must be thread-safe.

func (*SerialDo) Do 

func (sdo *SerialDo) Do(now ...time.Time) (isPending bool)

Do invokes the thunk serially if SerialDo is idle, Do launches thunk via a thread if SerialDo is busy, Do makes it pending if SerialDo is already pending, Do does nothing Do returns true if SerialDo state is pending Do is non-blocking and thread-safe

func (*SerialDo) State added in v0.4.26 

func (sdo *SerialDo) State() (
	busySince time.Time,
	pendingSince time.Time,
	isCancel bool,
	isWaitComplete bool,
)

func (*SerialDo) String added in v0.4.26 

func (sdo *SerialDo) String() (s string)

func (*SerialDo) Wait added in v0.4.26 

func (sdo *SerialDo) Wait()

type SerialDoCore added in v0.4.26 

type SerialDoCore struct {
	// contains filtered or unexported fields
}

func NewSerialDoCore added in v0.4.26 

func NewSerialDoCore(thunk func(at time.Time), errFn func(err error), ctx context.Context) (serialDoCore *SerialDoCore)

func (*SerialDoCore) Do added in v0.4.26 

func (sdo *SerialDoCore) Do(now ...time.Time) (isPending bool, isShutdown bool)

func (*SerialDoCore) Wait added in v0.4.26 

func (sdo *SerialDoCore) Wait(at time.Time)

type SerialDoEvent 

type SerialDoEvent struct {
	ID SerialDoID
	SerialDoType
	time.Time
	*SerialDo
}

func NewSerialDoEvent added in v0.4.26 

func NewSerialDoEvent(typ SerialDoType, t time.Time, serialDo *SerialDo) (event *SerialDoEvent)

func (*SerialDoEvent) String added in v0.4.26 

func (e *SerialDoEvent) String() (s string)

type SerialDoID added in v0.4.26 

type SerialDoID string

func (SerialDoID) String added in v0.4.26 

func (id SerialDoID) String() (s string)

type SerialDoType added in v0.4.26 

type SerialDoType uint8
const (
	// The SerialDo is invoking thunk from idle, now time
	SerialDoLaunch SerialDoType = 1 + iota
	// The SerialDo enqueued a future invocation, request time
	SerialDoPending
	// The SerialDo is launching a pending invocation, request time
	SerialDoPendingLaunch
	// The SerialDo returned to being idle, time is busy since
	SerialDoIdle
)

func (SerialDoType) IsValid added in v0.4.26 

func (e SerialDoType) IsValid() (isValid bool)

func (SerialDoType) String added in v0.4.26 

func (e SerialDoType) String() (s string)

type ServerFactory added in v0.3.0 

type ServerFactory interface {
	// Adb connects to an adb adb Android Debug Bridge server on a specified tcp socket
	Adb(address AdbSocketAddress, ctx context.Context) (server Serverette)
	// AdbLocalhost connects to an adb Android Debug Bridge server on the local computer
	AdbLocalhost(ctx context.Context) (server Serverette)
}

ServerFactory describes how AdbServer objects are obtained. Such servers may use duifferent protocol implementations from Adbette

type Serverette added in v0.3.0 

type Serverette interface {
	AdbAdressProvider // AdbSocketAddress()
	// DeviceSerialList lists serials for the currently online Android devices
	DeviceSerialList() (serials []AndroidSerial, err error)
	// DeviceStati lists all serials currently known to the server along with
	// their current status.
	// The two slices correspond and are of the same length
	DeviceStati() (serials []AndroidSerial, stati []AndroidStatus, err error)
	// TrackDevices emits serial numbers for devices that come online.
	// serials are sent on the serials channel.
	// if err is non-nil, set-up of failed.
	// The errs channel closes when watching stops
	// Watching is stopped by calling cancel function or when the server’s context terminates
	TrackDevices() (tracker Trackerette, err error)
}

Serverette is a generic representation of an adb server running on a host.

command-line adb: As of Android 12, Android Debug Bridge version 1.0.41 Version 32.0.0-8006631 has the following commands are supported: devices connect disconnect pair forward ppp reverse mdns push pull sync shell emu install install-multiple install-multiple-package uninstall bugreport jdwp logcat disable-verity enable-verity keygen wait-for* get-state get-serialno get-devpath remount reboot sideload root unroot usb tcpip start-server kill-server reconnect attach detach

type ServeretteFactory added in v0.3.0 

type ServeretteFactory interface {
	// Adb connects to an adb adb Android Debug Bridge server on a specified tcp socket.
	// address is a string default "localhost:5037" and default port ":5037".
	// adbetter is a factory for Adbette connections.
	NewServerette(address AdbSocketAddress, adbetter Adbetter, ctx context.Context) (server Serverette)
}

ServeretteFactory is a Server connection factory for Adbette implementations

type Stack added in v0.4.20 

type Stack interface {
	ID() ThreadID
	Status() ThreadStatus
	IsMain() (isMain bool)
	Frames() (frames []Frame)
	Creator() (creator *pruntime.CodeLocation)
	Shorts(prepend string) (s string)
	String() (s string)
}

type Statuser added in v0.3.0 

type Statuser interface {
	Set(status string) (statuser Statuser)
	Shutdown()
}

Statuser prints threads that do not react within a specified time frame. This is useful during early multi-threaded design when it is uncertain why work is not progressing. Is it your code or their code? Once the program concludes without hung threads, Tracer is the better tool to identify issues.

type StatuserFactory added in v0.3.0 

type StatuserFactory interface {
	NewStatuser(useStatuser bool, d time.Duration) (statuser Statuser)
}

type SubGo added in v0.4.15 

type SubGo interface {
	// Go: SubGo behaves like a Go
	Go
	// Wait allows a thread to wait for (many) sub-threads
	Wait()
	IsErr() (isNonFatal bool, isErrorExit bool)
	String() (s string)
}

SubGo allows an executing go statement provided a Go object to have sub-thread go statements. SubGo is a Go with individual cancel and obervable TraceGroup. Wait waits for all sub-threads to exit. Cancel affects all sub-threads.

type SyncAdd added in v0.4.20 

type SyncAdd interface {
	Add(delta int)
}

type SyncDone added in v0.4.20 

type SyncDone interface {
	Done()
}

type SyncWait added in v0.4.20 

type SyncWait interface {
	Wait()
}

type ThreadID added in v0.4.9 

type ThreadID string

ThreadID is an opaque type that uniquley identifies a thread, ie. a goroutine. goid.GoID obtains ThreadID for the executing thread. ThreadID is comparable, ie. can be used as a map key. ThreadID can be cast to string using .String() func (threadID ThreadID) String() (s string)

func (ThreadID) String added in v0.4.12 

func (threadID ThreadID) String() (s string)

type ThreadResult added in v0.4.9 

type ThreadResult struct {
	Err // Error() string
}

type ThreadStatus added in v0.4.12 

type ThreadStatus string

ThreadStatus indicates the current stat of a thread most often it is "running"

type Timer 

type Timer struct {
	Label string
	// contains filtered or unexported fields
}

Timer is a simple request timer

func NewTimer 

func NewTimer(label string) (t *Timer)

NewTimer gets a simple timer with duration or string output

func (*Timer) End 

func (t *Timer) End() (d time.Duration)

End gets duration

func (*Timer) Endms 

func (t *Timer) Endms() (ms string)

Endms gets tring with duration in ms

type TraceGroup added in v0.4.20 

type TraceGroup struct {
	WaitGroup
	// contains filtered or unexported fields
}

parl.TraceGroup is an observable sync.Waitgroup.

TraceGroup cannot be in parl because WaitAction imports goid

func (*TraceGroup) Add added in v0.4.20 

func (wg *TraceGroup) Add(delta int)

func (*TraceGroup) Done added in v0.4.20 

func (wg *TraceGroup) Done()

func (*TraceGroup) DoneBool added in v0.4.20 

func (wg *TraceGroup) DoneBool() (isZero bool)

func (*TraceGroup) String added in v0.4.20 

func (wg *TraceGroup) String() (s string)

type Tracer added in v0.3.0 

type Tracer interface {
	// AssignTaskToThread assigns a Thread to a task
	AssignTaskToThread(threadID ThreadID, task TracerTaskID) (tracer Tracer)
	// RecordTaskEvent adds an event to the task threadID is currently assigned to.
	// If threadID is not assigned, a new task is created.
	RecordTaskEvent(threadID ThreadID, text string) (tracer Tracer)
	// Records returns the current map of tasks and their events
	Records(clear bool) (records map[TracerTaskID][]TracerRecord)
}

Tracer lists events in terms of tasks rather than per time or thread. A task is executed by threads assigned to it. Threads are uniquely identified by threadID. A task can have zero or one threads assigned at any one time. A thread can be assigned to zero or one tasks. Each task has an ID, a name and a list of events and thread assignments Tracer can record branching in the code and return that for a particular item being processed. For an item processed incorrectly, or when threads hang, Tracer will find unfavorable branching and last known locations.

type TracerFactory added in v0.3.0 

type TracerFactory interface {
	// NewTracer creates tracer storage.
	// use false indicates a nil Tracer whose output will not be used
	NewTracer(use bool) (tracer Tracer)
}

type TracerRecord added in v0.3.0 

type TracerRecord interface {
	Values() (at time.Time, text string)
}

type TracerTaskID added in v0.3.0 

type TracerTaskID string

type Trackerette added in v0.3.0 

type Trackerette interface {
	// Serials emit serial number as online devices become available
	Serials() (serials <-chan AndroidSerial)
	// Errs is available once Serials close. It returns any errors
	Errs() (err error)
	// Cancel shuts down the Tracker
	Cancel()
}

Trackerette represents a server connection emitting device serial numbers

type UniqueID added in v0.4.26 

type UniqueID[T ~string] struct {
	// contains filtered or unexported fields
}

UniqueID is a executable-invocation-unique identifier generator. The identifier is a unique string. Usage: 

type MyType string
var generator parl.UniqueID[MyType]
someID := generator.ID()

func (*UniqueID[T]) ID added in v0.4.26 

func (u *UniqueID[T]) ID() (unique T)

ID generates a unique string identifier

type WaitAction added in v0.4.20 

type WaitAction struct {
	ID     ThreadID
	Loc    pruntime.CodeLocation
	IsDone bool
	Delta  int
}

func NewWaitAction added in v0.4.20 

func NewWaitAction(skipFrames int, delta int, isDone bool) (waitAction *WaitAction)

func (*WaitAction) String added in v0.4.20 

func (wa *WaitAction) String() (s string)

type WaitDo added in v0.4.20 

type WaitDo struct {
	Waiter
}

func (*WaitDo) IsExit added in v0.4.20 

func (w *WaitDo) IsExit() (isExit bool)

type WaitGroup added in v0.3.0 

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

parl.WaitGroup is like a sync.Waitgroup that can be inspected. The Waiting method returns the number of threads waited for. parl.WaitGroup requires no initialization. 

var wg parl.WaitGroup
wg.Add(1)
…
wg.Waiting()

func (*WaitGroup) Add added in v0.3.0 

func (wg *WaitGroup) Add(delta int)

func (*WaitGroup) Counters added in v0.4.12 

func (wg *WaitGroup) Counters() (adds int, dones int)

func (*WaitGroup) Done added in v0.3.0 

func (wg *WaitGroup) Done()

func (*WaitGroup) DoneBool added in v0.4.20 

func (wg *WaitGroup) DoneBool() (isExit bool)

func (*WaitGroup) IsZero added in v0.4.5 

func (wg *WaitGroup) IsZero() (isZero bool)

func (*WaitGroup) String added in v0.4.20 

func (wg *WaitGroup) String() (s string)

type Waitable added in v0.4.12 

type Waitable interface {
	Wait()
}

Waitable is the invoker’s Wait part of sync.WaitGroup and other implementations. Waitable is a many-to-many relation. Waitable allows the caller to await exit and free of all invocations. 

waitsForLots parl.WaitGroup
shutsDownLots parl.OnceChan
… = NewSomething(&waitsForLots, &shutsDownLots)
go someThread(&waitsForLots, &shutsDownLots)
func someThread(Doneable w, context.Context ctx) {
  defer w.Done()
  w.Add(2)
  go somethingElse()

type WaitedOn added in v0.4.20 

type WaitedOn interface {
	SyncAdd
	SyncDone
	DoneBool() (isExit bool)
	IsZero() (isZero bool)
}

type Waiter added in v0.4.20 

type Waiter interface {
	WaitedOn
	WaitingFor
}

waiter allows to use any of observable parl.WaitGroup or parl.TraceGroup

type WaitingFor added in v0.4.20 

type WaitingFor interface {
	SyncAdd
	IsZero() (isZero bool)
	Counters() (adds, dones int)
	SyncWait
	String() (s string)
}

Source Files

View all Source files

Directories

Path Synopsis
Package breakcycle breaks import cycles with parl
 Package breakcycle breaks import cycles with parl
Package errorglue contains non-essential error declarations
 Package errorglue contains non-essential error declarations
Package ev is deprecated by the github.com/haraldrudell/parl/g0 package 220429 Package ev provides standardized goroutine management events contain thread completions, failures and any type of data items.
 Package ev is deprecated by the github.com/haraldrudell/parl/g0 package 220429 Package ev provides standardized goroutine management events contain thread completions, failures and any type of data items.
Package evx is deprecated by the github.com/haraldrudell/parl/g0 package 220429 Package evx contains declarations not essential to event handling
 Package evx is deprecated by the github.com/haraldrudell/parl/g0 package 220429 Package evx contains declarations not essential to event handling
Package g0 facilitates launch, management and execution of goroutines
 Package g0 facilitates launch, management and execution of goroutines
goid.GoID() provides a unique goroutine identifier.
 goid.GoID() provides a unique goroutine identifier.
mains module
omaps module
Package parlca provides a self-signed certificate authority
 Package parlca provides a self-signed certificate authority
Package perrors enrichens error values with string data, stack traces, associated errors, less severe warnings, thread-safe containers and comprehensive error string representations.
 Package perrors enrichens error values with string data, stack traces, associated errors, less severe warnings, thread-safe containers and comprehensive error string representations.
Package pfs provides file-system related functions
 Package pfs provides file-system related functions
plog provides log instances with Log Logw Info Debug D SetDebug SetRegexp SetRegexp SetSilent IsThisDebug IsSilent.
 plog provides log instances with Log Logw Info Debug D SetDebug SetRegexp SetRegexp SetSilent IsThisDebug IsSilent.
Package pnet provides IP-related functions with few dependencies beyond the net package
 Package pnet provides IP-related functions with few dependencies beyond the net package
Package parlos provides simplified functions related to the os package Package parlos provides simplified functions related to the os package Package parlos provides simplified functions related to the os package
 Package parlos provides simplified functions related to the os package Package parlos provides simplified functions related to the os package Package parlos provides simplified functions related to the os package
process module
Package progress provides printable progress reporting for multi-threaded operations
 Package progress provides printable progress reporting for multi-threaded operations
Package pruntime provides an interface to the Go standard library’s runtime package using only serializable simple types Stack traces and code locations have several formats: codeLocation := pruntime.NewCodeLocation(0) codeLocation.Base() // package and type → mypackage.(*MyType).MyFunc codeLocation.PackFunc() // very brief → mypackage.MyFunc codeLocation.Name(): // function name only → MyFunc codeLocation.Short() // line, no package path → mypackage.(*MyType).MyFunc-myfile.go:19 codeLocation.Long() // uniquely identifiable → codeberg.org/haraldrudell/mypackage.(*MyType).MyFunc-myfile.go:19 codeLocation.Full() // everything → codeberg.org/haraldrudell/mypackage.(*MyType).MyFunc-/fs/mypackage/myfile.go:19 codeLocation.String() // two lines → "codeberg.org/haraldrudell/mypackage.(*MyType).MyFunc\n /fs/mypackage/myfile.go:19" Stack can determine where a goroutine was created and whether this is the main thread pruntime.GoRoutineID() → 1 pruntime.NewStack(0).Creator.Short() → main.main-pruntime.go:30 fmt.Println(pruntime.NewStack(0).IsMainThread) → true pruntime.NewStack(0).Frames[0].Args → (0x104c12c60?)
 Package pruntime provides an interface to the Go standard library’s runtime package using only serializable simple types Stack traces and code locations have several formats: codeLocation := pruntime.NewCodeLocation(0) codeLocation.Base() // package and type → mypackage.(*MyType).MyFunc codeLocation.PackFunc() // very brief → mypackage.MyFunc codeLocation.Name(): // function name only → MyFunc codeLocation.Short() // line, no package path → mypackage.(*MyType).MyFunc-myfile.go:19 codeLocation.Long() // uniquely identifiable → codeberg.org/haraldrudell/mypackage.(*MyType).MyFunc-myfile.go:19 codeLocation.Full() // everything → codeberg.org/haraldrudell/mypackage.(*MyType).MyFunc-/fs/mypackage/myfile.go:19 codeLocation.String() // two lines → "codeberg.org/haraldrudell/mypackage.(*MyType).MyFunc\n /fs/mypackage/myfile.go:19" Stack can determine where a goroutine was created and whether this is the main thread pruntime.GoRoutineID() → 1 pruntime.NewStack(0).Creator.Short() → main.main-pruntime.go:30 fmt.Println(pruntime.NewStack(0).IsMainThread) → true pruntime.NewStack(0).Frames[0].Args → (0x104c12c60?)
Package psql augments database/sql
 Package psql augments database/sql
pstrings provides FilteredJoin QuoteList StrSliceContains
 pstrings provides FilteredJoin QuoteList StrSliceContains
psyscall has functions to examine syscall.Errno errors
 psyscall has functions to examine syscall.Errno errors
pterm module
Package parltime provides time utility functions
 Package parltime provides time utility functions
sqliter module
Package threadprof provide profiling of threading
 Package threadprof provide profiling of threading
tracer has events by task then time rather than time or thread
 tracer has events by task then time rather than time or thread
watchfs module
yaml module
yamler module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.