github.com/m3db/m3@v1.5.0/src/m3em/os/exec/types.go (about)

     1  // Copyright (c) 2017 Uber Technologies, Inc.
     2  //
     3  // Permission is hereby granted, free of charge, to any person obtaining a copy
     4  // of this software and associated documentation files (the "Software"), to deal
     5  // in the Software without restriction, including without limitation the rights
     6  // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     7  // copies of the Software, and to permit persons to whom the Software is
     8  // furnished to do so, subject to the following conditions:
     9  //
    10  // The above copyright notice and this permission notice shall be included in
    11  // all copies or substantial portions of the Software.
    12  //
    13  // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    14  // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    15  // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    16  // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    17  // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    18  // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    19  // THE SOFTWARE.
    20  
    21  package exec
    22  
    23  import (
    24  	"fmt"
    25  )
    26  
    27  var (
    28  	// ErrPathNotSet indicates a Cmd object which doesn't have a path value
    29  	ErrPathNotSet = fmt.Errorf("cmd: no path specified")
    30  
    31  	// ErrArgsRequiresPathAsFirstArg indicates a Cmd object which doesn't have
    32  	// args[0] == path
    33  	ErrArgsRequiresPathAsFirstArg = fmt.Errorf("cmd: args[0] un-equal to path")
    34  )
    35  
    36  // EnvMap is a map of Key-Value pairs representing the environment variables.
    37  // NB(prateek): these are a set of 'delta' vars, i.e. they are appended to the
    38  // vars already present in `os.Environ()`.
    39  type EnvMap map[string]string
    40  
    41  // Cmd represents an executable command
    42  // NB(prateek): golang's os/exec package makes an implicit requirement that
    43  // Args[0] to be set to Path, iff Args is set at all. This package follows the
    44  // convention but makes that requirement explicit. ProcessMonitor reports
    45  // error when being constructed.
    46  type Cmd struct {
    47  	Path      string
    48  	Args      []string
    49  	OutputDir string
    50  	Env       EnvMap
    51  }
    52  
    53  // Validate ensures the provide Cmd object conforms to the expected structure.
    54  func (c Cmd) Validate() error {
    55  	if c.Path == "" {
    56  		return ErrPathNotSet
    57  	}
    58  	if len(c.Args) > 0 && c.Path != c.Args[0] {
    59  		return ErrArgsRequiresPathAsFirstArg
    60  	}
    61  	return nil
    62  }
    63  
    64  // ProcessListener permits users of the API to be notified of process termination
    65  type ProcessListener interface {
    66  	// OnComplete is executed in the event of process termination without error
    67  	OnComplete()
    68  
    69  	// OnError is executed in the event of process termination with error
    70  	OnError(error)
    71  }
    72  
    73  // ProcessMonitor provides necessary controls to supervise a process
    74  type ProcessMonitor interface {
    75  	// Start starts the provided process
    76  	Start() error
    77  
    78  	// Stop stops any running process
    79  	// NB(prateek): the golang runtime reports error inconsistently upon calling
    80  	// `process.Kill()`. Consequently, it is not guaranteed which notification method
    81  	// of the ProcessListener (OnComplete/OnError) is invoked upon process termination.
    82  	// Refer https://github.com/golang/go/blob/master/src/os/exec_plan9.go#L51-L63
    83  	Stop() error
    84  
    85  	// Running returns a flag indicating if the process is running
    86  	Running() bool
    87  
    88  	// Err returns any error encountered
    89  	Err() error
    90  
    91  	// Close releases any held resources
    92  	Close() error
    93  
    94  	// StdoutPath returns the path to the process stdout file
    95  	StdoutPath() string
    96  
    97  	// StderrPath returns the path to the process stderr file
    98  	StderrPath() string
    99  }