v0.4.116 deprecate AtomicBool AtomicReference

adderror.go → add-error.go

@@ -5,8 +5,11 @@ ISC License
 
 package parl
 
+// AddError is a function to submit non-fatal errors
 type AddError func(err error)
 
+// AddErrorIf is an interface implementing the AddError function
 type AddErrorIf interface {
+	// AddError is a function to submit non-fatal errors
 	AddError(err error)
 }

android-serial.go

@@ -5,14 +5,12 @@ ISC License
 
 package parl
 
-func NewAndroidSerial(s string) (serial AndroidSerial) {
-	return AndroidSerial(s)
-}
+// NewAndroidSerial returns Android serial for s
+//   - typically a string of a dozen or so 8-bit chanacters consisting of
+//     lower and upper case a-zA-Z0-9
+func NewAndroidSerial(s string) (serial AndroidSerial) { return AndroidSerial(s) }
 
-func (a AndroidSerial) String() (s string) {
-	return string(a)
-}
+// IsValid() returns whether a contains a valid Android serial
+func (a AndroidSerial) IsValid() (isValid bool) { return len(string(a)) > 0 }
 
-func (a AndroidSerial) IsValid() (isValid bool) {
-	return len(string(a)) > 0
-}
+func (a AndroidSerial) String() (s string) { return string(a) }

android-status.go

@@ -5,18 +5,14 @@ ISC License
 
 package parl
 
-func NewAndroidStatus(s string) (status AndroidStatus) {
-	return AndroidStatus(s)
-}
+// NewAndroidStatus returns Anddroid status of s
+//   - AndroidStatus is a single word of ANSII-set characters
+func NewAndroidStatus(s string) (status AndroidStatus) { return AndroidStatus(s) }
 
-func (a AndroidStatus) String() (s string) {
-	return string(a)
-}
+// IsValid returns whether a conatins a valid Android device status
+func (a AndroidStatus) IsValid() (isValid bool) { return len(string(a)) > 0 }
 
-func (a AndroidStatus) IsValid() (isValid bool) {
-	return len(string(a)) > 0
-}
+// IsOnline returns whether the Android status is device online, ie. ready for interactions
+func (a AndroidStatus) IsOnline() (isOnline bool) { return a == AndroidOnline }
 
-func (a AndroidStatus) IsOnline() (isOnline bool) {
-	return a == AndroidOnline
-}
+func (a AndroidStatus) String() (s string) { return string(a) }

atomic-counter.go

@@ -10,51 +10,47 @@ import (
 	"sync/atomic"
 )
 
-type AtomicCounter uint64
+// AtomicCounter is a uint64 thread-safe counter
+type AtomicCounter atomic.Uint64
 
-func (max *AtomicCounter) Inc() (value uint64) {
-	value = atomic.AddUint64((*uint64)(max), 1)
-	return
-}
+// Inc increments with wrap-around. Thread-Safe
+//   - value is new value
+func (a *AtomicCounter) Inc() (value uint64) { return (*atomic.Uint64)(a).Add(1) }
 
-func (max *AtomicCounter) Inc2() (value uint64, didInc bool) {
+// Inc2 is increment without wrap-around. Thread-Safe
+//   - at math.MaxUint64, increments are ineffective
+func (a *AtomicCounter) Inc2() (value uint64, didInc bool) {
 	for {
-		var beforeValue = atomic.LoadUint64((*uint64)(max))
+		var beforeValue = (*atomic.Uint64)(a).Load()
 		if beforeValue == math.MaxUint64 {
-			return
-		} else if didInc = atomic.CompareAndSwapUint64((*uint64)(max), beforeValue, beforeValue+1); didInc {
-			return
+			return // at max
+		} else if didInc = (*atomic.Uint64)(a).CompareAndSwap(beforeValue, beforeValue+1); didInc {
+			return // inc successful return
 		}
 	}
 }
 
-func (max *AtomicCounter) Dec() (value uint64) {
-	value = atomic.AddUint64((*uint64)(max), math.MaxUint64)
-	return
-}
+// Dec is decrement with wrap-around. Thread-Safe
+func (a *AtomicCounter) Dec() (value uint64) { return (*atomic.Uint64)(a).Add(math.MaxUint64) }
 
-func (max *AtomicCounter) Dec2() (value uint64, didDec bool) {
+// Dec2 is decrement with no wrap-around. Thread-Safe
+//   - at 0, decrements are ineffective
+func (a *AtomicCounter) Dec2() (value uint64, didDec bool) {
 	for {
-		var beforeValue = atomic.LoadUint64((*uint64)(max))
+		var beforeValue = (*atomic.Uint64)(a).Load()
 		if beforeValue == 0 {
-			return
-		} else if didDec = atomic.CompareAndSwapUint64((*uint64)(max), beforeValue, beforeValue-1); didDec {
-			return
+			return // no dec return
+		} else if didDec = (*atomic.Uint64)(a).CompareAndSwap(beforeValue, beforeValue-1); didDec {
+			return // dec successful return
 		}
 	}
 }
 
-func (max *AtomicCounter) Add(value uint64) (newValue uint64) {
-	newValue = atomic.AddUint64((*uint64)(max), value)
-	return
-}
+// Add is add with wrap-around. Thread-Safe
+func (a *AtomicCounter) Add(value uint64) (newValue uint64) { return (*atomic.Uint64)(a).Add(value) }
 
-func (max *AtomicCounter) Set(value uint64) (oldValue uint64) {
-	oldValue = atomic.SwapUint64((*uint64)(max), value)
-	return
-}
+// Set sets a new aggregate value. Thread-Safe
+func (a *AtomicCounter) Set(value uint64) (oldValue uint64) { return (*atomic.Uint64)(a).Swap(value) }
 
-func (max *AtomicCounter) Value() (value uint64) {
-	value = atomic.LoadUint64((*uint64)(max))
-	return
-}
+// Value returns current counter-value
+func (a *AtomicCounter) Value() (value uint64) { return (*atomic.Uint64)(a).Load() }

atomic-max.go

@@ -12,31 +12,39 @@ import (
 	"golang.org/x/exp/constraints"
 )
 
-type AtomicMax[T constraints.Integer] struct {
-	value    atomic.Uint64
-	hasValue atomic.Bool
-}
+// AtomicMax is a thread-safe max container
+type AtomicMax[T constraints.Integer] struct{ value, value0 atomic.Uint64 }
 
-func NewAtomicMax[T constraints.Integer](value T) (atomicMax *AtomicMax[T]) {
-	m := AtomicMax[T]{}
-	if value != 0 {
-		m.value.Store(uint64(value)) // set initial threshold
-	}
-	return &m
+// NewAtomicMax returns a thread-safe max container
+//   - T underlying type must be int
+//   - negative values are not allowed
+//   - to set initial value, use Init
+func NewAtomicMax[T constraints.Integer]() (atomicMax *AtomicMax[T]) { return &AtomicMax[T]{} }
+
+// Init performs actions that cannot happen prior to copying AtomicMax
+//   - supports functional chaining
+//   - Thread-safe
+func (m *AtomicMax[T]) Init(value T) (atomicMax *AtomicMax[T]) {
+	atomicMax = m
+	m.value.Store(uint64(value))
+	m.value0.Store(uint64(value)) // set initial threshold
+	return
 }
 
+// Value updates the container possibly with a new Max value
+//   - value cannot be negative
+//   - Thread-safe
 func (m *AtomicMax[T]) Value(value T) (isNewMax bool) {
 
 	// check if value is a new max
-	valueU64, err := ints.Unsigned[uint64](value, "")
+	var valueU64, err = ints.Unsigned[uint64](value, "")
 	if err != nil {
 		panic(err) // value out of range, ie. negative
 	}
 	var current = m.value.Load()
 	if isNewMax = valueU64 > current; !isNewMax {
 		return // not a new max return
 	}
-	m.hasValue.CompareAndSwap(false, true)
 
 	// store the new max
 	for {
@@ -51,10 +59,15 @@ func (m *AtomicMax[T]) Value(value T) (isNewMax bool) {
 	}
 }
 
+// Max returns current max and a flag whether a value is present
+//   - Thread-safe
 func (m *AtomicMax[T]) Max() (value T, hasValue bool) {
-	return T(m.value.Load()), m.hasValue.Load()
+	var u64 = m.value.Load()
+	value = T(u64)
+	hasValue = u64 != m.value0.Load()
+	return
 }
 
-func (m *AtomicMax[T]) Max1() (value T) {
-	return T(m.value.Load())
-}
+// Max1 returns current maximum whether default or set by Value
+//   - Thread-safe
+func (m *AtomicMax[T]) Max1() (value T) { return T(m.value.Load()) }