github.com/haraldrudell/parl@v0.4.176/parl.go (about) 1 /* 2 © 2020–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/) 3 ISC License 4 */ 5 6 /* 7 Package parl handles inter-thread communication and controls parallelism 8 9 parl has sub-packages augmenting the Go standard library: 10 11 perrors pfs plog pnet pos pruntime psql pstrings 12 psyscall pterm ptime 13 14 parl has feature packages: 15 16 ev — handling of goroutine-based functions 17 goid — unique goroutine IDs 18 mains — functions for writing command-line utilities and services 19 parlca — self-signed certificate authority 20 progress — monitor work progress for a large number of threads 21 sqlite — local SQL database 22 threadprof — profiling and counters for what threads are doing 23 // statuser: thread hang detector 24 tracer — event lists by task rather than by time or thread 25 26 parl features per-writer thread-safe logging with topic and per-package 27 output control: 28 29 Logging is to stderr except for the Out function. 30 parl logging uses comma separator for numbers. 31 One argument is output as string, two or more arguments is Printf. 32 The location matched against the regular expression is 33 full package path, optional type receiver and the funtion name: 34 “github.com/haraldrudell/mypackage.(*MyType).MyFunc” 35 36 Out(string, ...interface{}) — Standard output 37 Log(string, ...interface{}) — Always outputs to stderr 38 parl.D(string, ...interface{}) — Same as Log, intended for temporary use 39 40 Info(string, ...interface{}) — Informational progress messages 41 SetSilent(true) — removes Info output 42 IsSilent() — deteremines if Info printing applies 43 44 Debug(string, ...interface{}) — only prints for locations where SetDebug(true) 45 SetDebug(true) — Control Debug() globally, code location for all prints, long stack traces 46 SetRegexp(regExp string) (err error) — Regular expression controlling local Debug() printing 47 IsThisDebug() — Determines if debug is active for the executing function 48 49 Console(string, ...interface{}) — terminal interactivity output 50 51 parl.Recover() and parl.Recover2() thread recovery and mains.Executable.Recover() 52 process recovery: 53 54 Threads can provide their errors via the perrors.ParlError thread-safe error store, 55 plain error channels, parl.NBChan[error] or parl.ClosableChan[error]. 56 parl.Recover and parl.Recover2 convert thread panic to error along with regular errors, 57 annotating, retrieving and storing those errors and invoking error handling functions for them. 58 mains.Recover is similar for the process. 59 60 func thread(errCh *parl.NBChan[error]) { // real-time non-blocking error channel 61 defer errCh.Close() // non-blocking close effective on send complete 62 var err error 63 defer parl.Recover2("", &err, errCh.Send) 64 errCh.Ch() <- err // non-blocking 65 if err = someFunc(); err != nil { 66 err = perrors.Errorf("someFunc: %w", err) // labels and attaches a stack 67 return 68 … 69 func myThreadSafeThread(wg *sync.WaitGroup, errs *perrors.ParlError) { // ParlError: thread-safe error store 70 defer wg.Done() 71 var err error 72 defer parl.Recover(parl.Annotation(), &err, errs.AddErrorProc) 73 … 74 75 parl package features: 76 77 atomic.Bool — Thread-safe boolean 78 Closer — Deferrable, panic-free channel close 79 ClosableChan — Initialization-free channel with observable deferrable panic-free close 80 Moderator — A ticketing system for limited parallelism 81 NBChan — A non-blocking channel with trillion-size dynamic buffer 82 SerialDo — Serialization of invocations 83 WaitGroup —Observable WaitGroup 84 Debouncer — Invocation debouncer, pre-generics 85 Sprintf — Supporting thousands separator 86 87 # Parl is about 15,000 lines of Go code with first line written on November 21, 2018 88 89 # On March 16th, 2022, parl was open-sourced under an ISC License 90 91 © 2018–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/) 92 */ 93 package parl 94 95 const ( 96 Rfc3339s = "2006-01-02 15:04:05Z07:00" 97 Rfc3339ms = "2006-01-02 15:04:05.000Z07:00" 98 Rfc3339us = "2006-01-02 15:04:05.000000Z07:00" 99 Rfc3339ns = "2006-01-02 15:04:05.000000000Z07:00" 100 ) 101 102 type FSLocation interface { 103 Directory() (directory string) 104 } 105 106 // ThreadStatus indicates the current stat of a thread 107 // most often it is "running" 108 type ThreadStatus string