proc

package module
v0.1.6 Latest Latest
Warning

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

 Go to latest Published: Aug 3, 2022 License: Unlicense Imports: 17 Imported by: 12

README

proc

Process control, logging and child processes

Description

Golang is a great language for concurrency, but sometimes you want parallelism, and it's often simpler to design apps as little units that plug together via RPC APIs. Services don't always have easy start/stop/reconfig/restart controls, and sometimes they use their own custom configuration scheme that is complicated to integrate with yours.

In addition, you may want to design your applications as neat little pieces, but how to attach them together and orchestrate them starting up and coming down cleanly, and not have to deal with several different ttys to get the logs.

Proc creates a simple framework for creating observable, controllable execution units out of your code, and more easily integrating the code of others.

This project is the merge of several libraries for logging, spawning and controlling child processes, and creating an RPC to child processes that controls the run of the child process. Due to the confusing duplication of signals as a means of control and the lack of uniformity in signals (ie windows) the goal of proc is to create one way to do, following the principles of design used for Go itself.

Badges

<insert badges here

Installation

For developers:

To make nice tagged versions with the version number in the commit as well as matching to the tag, there is a tool called bumper that bumps the version to the next patch version (vX.X.PATCH), embeds this new version number into version.go with the matching corresponding git commit hash. This will make importing this library at an exact commit much more human.

In addition, it makes it easy to make a nice multi line commit message as many repositories request in their CONTRIBUTION file by replacing -- with two carriage returns.

To install:

go install ./bumper/.

To use:

bumper make a commit comment here -- text after double \
    hyphen will be separated by a carriage return -- \
    anywhere in the text

To automatically bump the minor version use minor as the first word of the comment. For the major version major.

Usage

reasonably include in the README.

Support

Roadmap

  • Implement basic logger v0.0.x
  • Create concurrent safe configuration CLI/env/config system v0.1.x
    • Created types with mutex/atomic locks to prevent concurrent access
    • Created key value map type containing collections of concurrent safe values with concurrent safe access to members
    • Create JSON marshal/unmarshal for configuration collections
    • Created tests for generating and concurrently accessing/mutating data
    • Save and load configuration from file (using json, with all values stored in file, no unnecessary comments)
    • Generate CLI help texts from configs specifications
    • Read values from environment variables overlay on config file values
    • Created command line parsing system overlay values above previous
  • Child process control system v0.2.x
    • Launch, pause, continue and stop child process. Use only one method: the IPC API, no complication with signals.
    • Read and pass through logging from child process
    • Correctly handle process signals from OS/tty to trigger orderly shutdown of child processes and leave none orphaned

Contributing

Authors and acknowledgment

David Vennik david@cybriq.systems

License

Unlicenced: see here

Project status

In the process of revision and merging together several related libraries that need to be unified.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (

	// App is the name of the application. Change this at the beginning of
	// an application main.
	App = "  main"
	// AllSubsystems stores all of the package subsystem names found in the current
	// application.
	AllSubsystems []string
)
View Source 
var (
	// URL is the git URL for the repository
	URL = "github.com/cybriq/proc"
	// GitRef is the gitref, as in refs/heads/branchname
	GitRef = "refs/heads/master"
	// ParentGitCommit is the commit hash of the parent HEAD
	ParentGitCommit = "9a17a7a12d991bae71e3ad6d9f3145ef6c920384"
	// BuildTime stores the time when the current binary was built
	BuildTime = "2022-08-03T15:30:37+02:00"
	// SemVer lists the (latest) git tag on the build
	SemVer = "v0.1.6"
	// PathBase is the path base returned from runtime caller
	PathBase = "/home/davidvennik/src/github.com/cybriq/proc/"
	// Major is the major number from the tag
	Major = 0
	// Minor is the minor number from the tag
	Minor = 1
	// Patch is the patch version number from the tag
	Patch = 6
)
View Source 
var LevelSpecs = map[LogLevel]LevelSpec{
	Off:   gLS(Off, 0, 0, 0),
	Fatal: gLS(Fatal, 255, 0, 0),
	Error: gLS(Error, 255, 128, 0),
	Check: gLS(Check, 255, 255, 0),
	Warn:  gLS(Warn, 255, 255, 0),
	Info:  gLS(Info, 0, 255, 0),
	Debug: gLS(Debug, 0, 128, 255),
	Trace: gLS(Trace, 128, 0, 255),
}

LevelSpecs specifies the id, string name and color-printing function

View Source 
var LvlStr = map[LogLevel]string{
	Off:   "off  ",
	Fatal: "fatal",
	Error: "error",
	Warn:  "warn ",
	Info:  "info ",
	Check: "check",
	Debug: "debug",
	Trace: "trace",
}

LvlStr is a map that provides the uniform width strings that are printed to identify the LogLevel of a log entry.

Functions

func Add added in v0.0.30 

func Add(pathBase string) (subsystem string)

Add adds a subsystem to the list of known subsystems and returns the string so it is nice and neat in the package logg.go file

func GetLoc added in v0.0.30 

func GetLoc(skip int, subsystem string) (output string)

GetLoc calls runtime.Caller and formats as expected by source code editors for terminal hyperlinks

Regular expressions and the substitution texts to make these clickable in Tilix and other RE hyperlink configurable terminal emulators:

This matches the shortened paths generated in this command and printed at the very beginning of the line as this logger prints: 

^((([\/a-zA-Z@0-9-_.]+/)+([a-zA-Z@0-9-_.]+)):([0-9]+))
/usr/local/bin/goland --line $5 $GOPATH/src/github.com/p9c/matrjoska/$2

I have used a shell variable there but tilix doesn't expand them, so put your GOPATH in manually, and obviously change the repo subpath.

func IfErrNotNilPanic added in v0.1.2 

func IfErrNotNilPanic(err error)

IfErrNotNilPanic is a helper for functions that should never error as errors are purely programmer errors and not error conditions.

func Item added in v0.0.30 

func Item(m *types.Metadata) (t types.Item)

Item takes a Metadata and creates the appropriate item type for it.

func List added in v0.0.30 

func List(items ...string) []string

List is a helper that uses variadic parameters to return a slice of strings.

func SetLogLevel added in v0.0.30 

func SetLogLevel(l LogLevel)

func SetTimeStampFormat added in v0.0.30 

func SetTimeStampFormat(format string)

SetTimeStampFormat sets a custom timeStampFormat for the logger

func Version added in v0.0.30 

func Version() string

Version returns a pretty printed version information string

Types

type BooT added in v0.1.2 

type BooT struct {
	*types.Metadata
	// contains filtered or unexported fields
}

BooT is a boolean item type

func NewBool added in v0.0.30 

func NewBool(m *types.Metadata) (b *BooT)

NewBool creates a new boolean types.Item

func (BooT) Bool added in v0.1.2 

func (b BooT) Bool() bool

func (BooT) Duration added in v0.1.2 

func (b BooT) Duration() time.Duration

func (BooT) Float added in v0.1.2 

func (b BooT) Float() float64

func (*BooT) FromString added in v0.1.2 

func (b *BooT) FromString(s string) error

func (BooT) Int added in v0.1.2 

func (b BooT) Int() int64

func (BooT) List added in v0.1.2 

func (b BooT) List() []string

func (BooT) Meta added in v0.1.6 

func (b BooT) Meta() *types.Metadata

func (*BooT) Set added in v0.1.2 

func (b *BooT) Set(bo bool)

func (BooT) String added in v0.1.2 

func (b BooT) String() string

func (BooT) Uint added in v0.1.2 

func (b BooT) Uint() uint64

type Chk 

type Chk func(e error) bool

Chk is a shortcut for printing if there is an error, or returning true

type Configs added in v0.0.30 

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

Configs are a concurrent safe key value store for configuration items

func Create added in v0.0.30 

func Create(items ...types.Desc) (c Configs)

Create a new configuration from a slice of item Desc riptors.

func (*Configs) Get added in v0.0.30 

func (c *Configs) Get(name string) (t types.Item, err error)

Get returns a named item from the Configs

func (*Configs) GetAllNames added in v0.1.6 

func (c *Configs) GetAllNames() (items []string)

GetAllNames returns a lexicographically sorted list of all item names in the Configs.

func (*Configs) GetHelp added in v0.1.6 

func (c *Configs) GetHelp(name, group string, detailed,
	markdown bool) (text string,
	err error)

func (*Configs) Load added in v0.1.4 

func (c *Configs) Load(filename string) (err error)

func (*Configs) MarshalJSON added in v0.0.30 

func (c *Configs) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON for the current state of a Configs

func (*Configs) Save added in v0.1.4 

func (c *Configs) Save(filename string) (err error)

func (*Configs) UnmarshalJSON added in v0.0.30 

func (c *Configs) UnmarshalJSON(bytes []byte) error

UnmarshalJSON loads a Configs with the values in a JSON string

type DurT added in v0.0.35 

type DurT struct {
	*types.Metadata
	// contains filtered or unexported fields
}

DurT is a duration item type

func NewDuration added in v0.0.30 

func NewDuration(m *types.Metadata) (b *DurT)

NewDuration creates a new duration types.Item

func (DurT) Bool added in v0.0.35 

func (d DurT) Bool() bool

func (DurT) Duration added in v0.0.35 

func (d DurT) Duration() time.Duration

func (DurT) Float added in v0.0.35 

func (d DurT) Float() float64

func (*DurT) FromString added in v0.0.35 

func (d *DurT) FromString(s string) error

func (DurT) Int added in v0.0.35 

func (d DurT) Int() int64

func (DurT) List added in v0.0.35 

func (d DurT) List() []string

func (DurT) Meta added in v0.1.6 

func (d DurT) Meta() *types.Metadata

func (*DurT) Set added in v0.0.35 

func (d *DurT) Set(du time.Duration)

func (DurT) String added in v0.0.35 

func (d DurT) String() string

func (DurT) Uint added in v0.0.35 

func (d DurT) Uint() uint64

type FltT added in v0.0.35 

type FltT struct {
	*types.Metadata
	// contains filtered or unexported fields
}

FltT is a float64 item type

func NewFloat added in v0.0.30 

func NewFloat(m *types.Metadata) (b *FltT)

NewFloat creates a new floating point types.Item

func (FltT) Bool added in v0.0.35 

func (f FltT) Bool() bool

func (FltT) Duration added in v0.0.35 

func (f FltT) Duration() time.Duration

func (FltT) Float added in v0.0.35 

func (f FltT) Float() float64

func (*FltT) FromString added in v0.0.35 

func (f *FltT) FromString(s string) error

func (FltT) Int added in v0.0.35 

func (f FltT) Int() int64

func (FltT) List added in v0.0.35 

func (f FltT) List() []string

func (FltT) Meta added in v0.1.6 

func (f FltT) Meta() *types.Metadata

func (*FltT) Set added in v0.0.35 

func (f *FltT) Set(fl float64)

func (FltT) String added in v0.0.35 

func (f FltT) String() string

func (FltT) Uint added in v0.0.35 

func (f FltT) Uint() uint64

type IntT added in v0.0.35 

type IntT struct {
	*types.Metadata
	// contains filtered or unexported fields
}

IntT is an int64 item type

func NewInt added in v0.0.30 

func NewInt(m *types.Metadata) (b *IntT)

NewInt creates a new integer types.Item

func (IntT) Bool added in v0.0.35 

func (in IntT) Bool() bool

func (IntT) Duration added in v0.0.35 

func (in IntT) Duration() time.Duration

func (IntT) Float added in v0.0.35 

func (in IntT) Float() float64

func (*IntT) FromString added in v0.0.35 

func (in *IntT) FromString(s string) error

func (IntT) Int added in v0.0.35 

func (in IntT) Int() int64

func (IntT) List added in v0.0.35 

func (in IntT) List() []string

func (IntT) Meta added in v0.1.6 

func (in IntT) Meta() *types.Metadata

func (*IntT) Set added in v0.0.35 

func (in *IntT) Set(i int64)

func (IntT) String added in v0.0.35 

func (in IntT) String() string

func (IntT) Uint added in v0.0.35 

func (in IntT) Uint() uint64

type LevelPrinter 

type LevelPrinter struct {
	Ln Println
	// F prints like fmt.Println surrounded by log details
	F Printf
	// S uses spew.dump to show the content of a variable
	S Prints
	// C accepts a function so that the extra computation can be avoided if
	// it is not being viewed
	C Printc
	// Chk is a shortcut for printing if there is an error, or returning
	// true
	Chk Chk
}

LevelPrinter defines a set of terminal printing primitives that output with extra data, time, level, and code location

type LevelSpec 

type LevelSpec struct {
	Name      string
	Colorizer func(format string, a ...interface{}) string
}

LevelSpec is a key pair of log level and the text colorizer used for it.

type LogLevel 

type LogLevel int32

LogLevel is a code representing a scale of importance and context for log entries. 

const (
	Off LogLevel = iota
	Fatal
	Error
	Check
	Warn
	Info
	Debug
	Trace
)

The LogLevel settings used in proc

type Logger 

type Logger struct {
	F, E, W, I, D, T LevelPrinter
}

Logger is a set of log printers for the various LogLevel items.

func GetLogger added in v0.0.30 

func GetLogger(pathBase string) (l *Logger)

GetLogger returns a set of LevelPrinter with their subsystem preloaded

type LstT added in v0.0.35 

type LstT struct {
	*sync.Mutex
	*types.Metadata
	// contains filtered or unexported fields
}

LstT is a []string item type

func NewList added in v0.0.30 

func NewList(m *types.Metadata) (b *LstT)

NewList creates a new list of strings types.Item

func (LstT) Bool added in v0.0.35 

func (l LstT) Bool() bool

func (LstT) Duration added in v0.0.35 

func (l LstT) Duration() time.Duration

func (LstT) Float added in v0.0.35 

func (l LstT) Float() float64

func (*LstT) FromString added in v0.0.35 

func (l *LstT) FromString(s string) error

func (LstT) Int added in v0.0.35 

func (l LstT) Int() int64

func (LstT) List added in v0.0.35 

func (l LstT) List() (li []string)

func (LstT) Meta added in v0.1.6 

func (l LstT) Meta() *types.Metadata

func (*LstT) Set added in v0.0.35 

func (l *LstT) Set(li ...string)

func (LstT) String added in v0.0.35 

func (l LstT) String() (o string)

func (LstT) Uint added in v0.0.35 

func (l LstT) Uint() uint64

type Printc 

type Printc func(closure func() string)

Printc accepts a function so that the extra computation can be avoided if it is not being viewed

type Printf 

type Printf func(format string, a ...interface{})

Printf prints like fmt.Println surrounded by log details

type Println 

type Println func(a ...interface{})

Println prints lists of interfaces with spaces in between

type Prints 

type Prints func(a ...interface{})

Prints prints a spew.Sdump for an interface slice

type StrT added in v0.0.35 

type StrT struct {
	*types.Metadata
	// contains filtered or unexported fields
}

StrT is a string item type

func NewString added in v0.0.30 

func NewString(m *types.Metadata) (b *StrT)

NewString creates a new string types.Item

func (StrT) Bool added in v0.0.35 

func (s StrT) Bool() bool

func (StrT) Duration added in v0.0.35 

func (s StrT) Duration() time.Duration

func (StrT) Float added in v0.0.35 

func (s StrT) Float() float64

func (*StrT) FromString added in v0.0.35 

func (s *StrT) FromString(st string) error

func (StrT) Int added in v0.0.35 

func (s StrT) Int() int64

func (StrT) List added in v0.0.35 

func (s StrT) List() []string

func (StrT) Meta added in v0.1.6 

func (s StrT) Meta() *types.Metadata

func (*StrT) Set added in v0.0.35 

func (s *StrT) Set(st string)

func (StrT) String added in v0.0.35 

func (s StrT) String() string

func (StrT) Uint added in v0.0.35 

func (s StrT) Uint() uint64

type UinT added in v0.0.35 

type UinT struct {
	*types.Metadata
	// contains filtered or unexported fields
}

UinT is an uint64 item type

func NewUint added in v0.0.30 

func NewUint(m *types.Metadata) (b *UinT)

NewUint creates a new unsigned integer types.Item

func (UinT) Bool added in v0.0.35 

func (u UinT) Bool() bool

func (UinT) Duration added in v0.0.35 

func (u UinT) Duration() time.Duration

func (UinT) Float added in v0.0.35 

func (u UinT) Float() float64

func (*UinT) FromString added in v0.0.35 

func (u *UinT) FromString(s string) error

func (UinT) Int added in v0.0.35 

func (u UinT) Int() int64

func (UinT) List added in v0.0.35 

func (u UinT) List() []string

func (UinT) Meta added in v0.1.6 

func (u UinT) Meta() *types.Metadata

func (*UinT) Set added in v0.0.35 

func (u *UinT) Set(ui uint64)

func (UinT) String added in v0.0.35 

func (u UinT) String() string

func (UinT) Uint added in v0.0.35 

func (u UinT) Uint() uint64

Source Files

View all Source files

Directories

Path Synopsis
cmd
bumper command
logtest command
gen command

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.