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