github.com/haraldrudell/parl@v0.4.176/if-value-stream.go (about)

     1  /*
     2  © 2024–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/)
     3  ISC License
     4  */
     5  
     6  package parl
     7  
     8  // ValueSink allows a thread to submit data to other threads
     9  //   - implemented by [github.com/haraldrudell/parl.AwaitableSlice]
    10  type ValueSink[T any] interface {
    11  	// Send submits single value
    12  	Send(value T)
    13  	// SendSlice submits any number of values
    14  	SendSlice(values []T)
    15  	// EmptyCh provides close-like behavior
    16  	//	- this thread invoking EmptyCh() signals end of values
    17  	//	- other threads invoking EmptyCh(parl.CloseAwaiter) awaits:
    18  	//	- — the EmptyCh() invocation and
    19  	//	- — the AwaitableSlice becoming empty
    20  	EmptyCh(doNotInitialize ...bool) (ch AwaitableCh)
    21  }
    22  
    23  // DataSink allows a thread to submit data to other threads
    24  //   - implemented by [github.com/haraldrudell/parl.AwaitableSlice]
    25  type ValueSource[T any] interface {
    26  	// Get obtains a single value
    27  	Get() (value T, hasValue bool)
    28  	// GetSlice obtains values by the slice
    29  	//	- nil slice means source is currently empty
    30  	GetSlice() (values []T)
    31  	// GetAll receives a combined slice of all values
    32  	//	- may cause allocation
    33  	GetAll() (values []T)
    34  	// Init allows for AwaitableSlice to be used in a for clause
    35  	//   - returns zero-value for a short variable declaration in
    36  	//     a for init statement
    37  	//
    38  	// Usage:
    39  	//
    40  	//	var a AwaitableSlice[…] = …
    41  	//	for value := a.Init(); a.Condition(&value); {
    42  	//	  // process received value
    43  	//	}
    44  	//	// the AwaitableSlice closed
    45  	Init() (value T)
    46  	// Condition allows for AwaitableSlice to be used in a for clause
    47  	//   - updates a value variable and returns whether values are present
    48  	//
    49  	// Usage:
    50  	//
    51  	//	var a AwaitableSlice[…] = …
    52  	//	for value := a.Init(); a.Condition(&value); {
    53  	//	  // process received value
    54  	//	}
    55  	//	// the AwaitableSlice closed
    56  	Condition(valuep *T) (hasValue bool)
    57  	// DataWaitCh returns an awaitable closing channel that
    58  	//	- is closed if data is available or
    59  	//	- closes once data becomes available
    60  	DataWaitCh() (ch AwaitableCh)
    61  	// EmptyCh provides close-like behavior
    62  	//	- this thread invoking EmptyCh(parl.CloseAwaiter) returns a
    63  	//		channel that closes on stream completion:
    64  	//	- — EmptyCh() invocation with no value by other thread and
    65  	//	- — the AwaitableSlice becoming empty
    66  	EmptyCh(doNotInitialize ...bool) (ch AwaitableCh)
    67  }