Documentation

Overview

    Package common implements code and utilities shared across all packages in client/.

    Index

    Examples

    Constants

    This section is empty.

    Variables

    View Source
    var ErrCanceled = errors.New("canceled")

      ErrCanceled is the default reason (error) for cancelation of Cancelable.

      Functions

      func CancelOnCtrlC

      func CancelOnCtrlC(c Canceler)

        CancelOnCtrlC makes a Canceler to be canceled on Ctrl-C (os.Interrupt).

        It is fine to call this function multiple times on multiple Canceler.

        func IsTerminal

        func IsTerminal(out io.Writer) bool

          IsTerminal returns true if the specified io.Writer is a terminal.

          func IsWindows

          func IsWindows() bool

            IsWindows returns True when running on the best OS there is.

            func WalkFuncSkipFile

            func WalkFuncSkipFile(file os.FileInfo) error

              WalkFuncSkipFile is a helper for implemenations of filepath.WalkFunc. The value that it returns may in turn be returned by the WalkFunc implementaiton to indicate that file should be skipped.

              Types

              type Cancelable

              type Cancelable interface {
              	// Cancel asks to cancel execution asynchronously.
              	//
              	// If reason is nil, default ErrCanceled is used.
              	// Calling more than once is a no-op: the call is ingored.
              	//
              	// Cancel opportunistically asks to stop execution, but does not wait
              	// for execution to actually stop. It is thus suitable to be called from
              	// any other goroutine and will not cause a deadlock.
              	Cancel(reason error)
              
              	// CancelationReason returns the reason provided by the first Cancel() call,
              	// or nil if not yet canceled.
              	CancelationReason() error
              }

                Cancelable implements asynchronous cancelation of execution.

                Typical implementation of Cancelable is a pipeline step doing work asynchronously in some goroutine. Calling Cancel would ask this goroutine to stop processing as soon as possible.

                type Canceler

                type Canceler interface {
                	Cancelable
                	// Close releases all resources and makes the instance unusable.
                	// Returns error to implement io.Closer , but it is always nil.
                	// Calling more than once is a no-op: the call does nothing.
                	io.Closer
                
                	// Channel returns the channel producing reason values once Cancel() is
                	// called. When Close() is called, this channel is closed.
                	//
                	// Use it in producers to ublock when Cancel() is called:
                	//	func produce(out chan <- interface{}, item interface{}) error {
                	//		select {
                	//			case reason, ok := <- Canceler.Channel():
                	//				if !ok {
                	//					// Canceler is closed; for us it's just as Canceled.
                	//					return ErrCanceled
                	//				}
                	//				return reason // Canceled with this reason.
                	//			case out := <- item:
                	//				return nil
                	//		}
                	//	}
                	Channel() <-chan error
                }

                  Canceler implements Cancelable, and assists in graceful interrupt and error handling in pipelines with channels.

                  func NewCanceler

                  func NewCanceler() Canceler

                    NewCanceler returns a new instance of canceler.

                    Call Cancel() once no longer used to release resources.

                    type FilesystemView

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

                      FilesystemView provides a filtered "view" of a filesystem. It translates absolute paths to relative paths based on its configured root path. It also hides any paths which match a blacklist entry.

                      func NewFilesystemView

                      func NewFilesystemView(root string, blacklist []string) (FilesystemView, error)

                        NewFilesystemView returns a FilesystemView based on the supplied root and blacklist, or an error if blacklist contains a bad pattern. root is the the base path used by RelativePath to calulate relative paths. blacklist is a list of globs of files to ignore. See RelativePath for more information.

                        func (FilesystemView) RelativePath

                        func (ff FilesystemView) RelativePath(path string) (string, error)

                          RelativePath returns a version of path which is relative to the FilesystemView root, or an empty string if path matches a blacklist entry.

                          Blacklist globs are matched against the entirety of each of:

                          * the path relative to the FilesystemView root.
                          * the basename return by filepath.Base(path).
                          

                          See filepath.Match for details about the format of blacklist globs.

                          type Flags

                          type Flags struct {
                          	Quiet     bool
                          	Verbose   bool
                          	TracePath string
                          }

                            Flags contains values parsed from command line arguments.

                            func (*Flags) Init

                            func (d *Flags) Init(f *flag.FlagSet)

                              Init registers flags in a given flag set.

                              func (*Flags) MakeLoggingContext

                              func (d *Flags) MakeLoggingContext(out io.Writer) context.Context

                                MakeLoggingContext makes a luci-go/common/logging compatible context using gologger onto the given writer.

                                The default logging level will be Info, with Warning and Debug corresponding to quiet/verbose respectively.

                                func (*Flags) Parse

                                func (d *Flags) Parse() error

                                  Parse applies changes specified by command line flags.

                                  func (*Flags) StartTracing

                                  func (d *Flags) StartTracing() (io.Closer, error)

                                    StartTracing enables tracing and returns a closer that must be called on process termination.

                                    type GoroutinePool

                                    type GoroutinePool interface {
                                    	Canceler
                                    
                                    	// Wait blocks until all started jobs finish.
                                    	//
                                    	// Returns nil if all jobs have been executed, or reason for cancelation of
                                    	// some jobs. This call is not itself cancelable, meaning that it'll block
                                    	// until all worker goroutines are finished.
                                    	Wait() error
                                    	// Schedule adds a new job for execution as a separate goroutine. If the
                                    	// GoroutinePool is canceled, onCanceled is called instead. It is fine to
                                    	// pass nil as onCanceled.
                                    	Schedule(job func(), onCanceled func())
                                    }

                                      GoroutinePool executes at a limited number of jobs concurrently, queueing others.

                                      GoroutinePool implements Canceler allowing canceling all not yet started jobs.

                                      func NewGoroutinePool

                                      func NewGoroutinePool(maxConcurrentJobs int, canceler Canceler) GoroutinePool

                                        NewGoroutinePool creates a new GoroutinePool with at most maxConcurrentJobs.

                                        Example
                                        Output:
                                        
                                        knock!knock!
                                        canceled because pool is no more
                                        all jobs either executed or canceled (pool is no more)
                                        

                                        type GoroutinePriorityPool

                                        type GoroutinePriorityPool interface {
                                        	Canceler
                                        
                                        	// Wait blocks until all started jobs finish.
                                        	//
                                        	// Returns nil if all jobs have been executed, or reason for cancelation of
                                        	// some jobs. This call is not itself cancelable, meaning that it'll block
                                        	// until all worker goroutines are finished.
                                        	Wait() error
                                        	// Schedule adds a new job for execution as a separate goroutine.
                                        	//
                                        	// If the GoroutinePriorityPool is canceled, onCanceled is called instead. It
                                        	// is fine to pass nil as onCanceled. Smaller values of priority imply earlier
                                        	// execution.
                                        	Schedule(priority int64, job func(), onCanceled func())
                                        }

                                          GoroutinePriorityPool executes at a limited number of jobs concurrently, queueing others.

                                          GoroutinePriorityPool implements Canceler allowing canceling all not yet started jobs.

                                          func NewGoroutinePriorityPool

                                          func NewGoroutinePriorityPool(maxConcurrentJobs int, canceler Canceler) GoroutinePriorityPool

                                            NewGoroutinePriorityPool creates a new goroutine pool with at most maxConcurrentJobs and schedules jobs according to priority.

                                            type Strings

                                            type Strings []string

                                              Strings accumulates string values from repeated flags.

                                              Use with flag.Var to accumulate values from "-flag s1 -flag s2".

                                              func (*Strings) Set

                                              func (c *Strings) Set(value string) error

                                                Set is needed to implements flag.Var interface.

                                                func (*Strings) String

                                                func (c *Strings) String() string