github.com/haraldrudell/parl@v0.4.176/if-pq.go (about) 1 /* 2 © 2023–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/) 3 ISC License 4 */ 5 6 package parl 7 8 import "golang.org/x/exp/constraints" 9 10 // AggregatingPriorityQueue uses cached priority obtained from 11 // Aggregators that operates on the values outside of the AggregatingPriorityQueue. 12 // - the Update method reprioritizes an updated value element 13 type AggregatingPriorityQueue[V any, P constraints.Ordered] interface { 14 // Get retrieves a possible value container associated with valuep 15 Get(valuep *V) (aggregator Aggregator[V, P], ok bool) 16 // Put stores a new value container associated with valuep 17 // - the valuep is asusmed to not have a node in the queue 18 Put(valuep *V, aggregator Aggregator[V, P]) 19 // Update re-prioritizes a value 20 Update(valuep *V) 21 // Clear empties the priority queue. The hashmap is left intact. 22 Clear() 23 // List returns the first n or default all values by pirority 24 List(n ...int) (aggregatorQueue []AggregatePriority[V, P]) 25 } 26 27 // PriorityQueue is a pointer-identity-to-value map of updatable values traversable by rank. 28 // - PriorityQueue operates directly on value by caching priority from the pritority function. 29 // - the AddOrUpdate method reprioritizes an updated value element 30 // - V is a value reference composite type that is comparable, ie. not slice map function. 31 // Preferrably, V is interface or pointer to struct type. 32 // - P is an ordered type such as Integer Floating-Point or string, used to rank the V values 33 // - values are added or updated using AddOrUpdate method distinguished by 34 // (computer science) identity 35 // - if the same comparable value V is added again, that value is re-ranked 36 // - priority P is computed from a value V using the priorityFunc function. 37 // The piority function may be examining field values of a struct 38 // - values can have the same rank. If they do, equal rank is provided in insertion order 39 // - pqs.NewPriorityQueue[V any, P constraints.Ordered] 40 // - pqs.NewRankingThreadSafe[V comparable, R constraints.Ordered]( 41 // ranker func(value *V) (rank R))) 42 type PriorityQueue[V any, P constraints.Ordered] interface { 43 // AddOrUpdate adds a new value to the prioirty queue or updates the priority of a value 44 // that has changed. 45 AddOrUpdate(value *V) 46 // List returns the first n or default all values by priority 47 List(n ...int) (valueQueue []*V) 48 } 49 50 // AggregatePriority caches the priority value from an aggregator for priority. 51 // - V is the value type used as a pointer 52 // - P is the priority type descending order, ie. Integer Floating-Point string 53 type AggregatePriority[V any, P constraints.Ordered] interface { 54 // Aggregator returns the aggregator associated with this AggregatePriority 55 Aggregator() (aggregator Aggregator[V, P]) 56 // Update caches the current priority from the aggregator 57 Update() 58 // Priority returns the effective cached priority 59 // - Priority is used by consumers of the AggregatingPriorityQueue 60 CachedPriority() (priority P) 61 // Index indicates insertion order 62 // - used for ordering elements of equal priority 63 Index() (index int) 64 } 65 66 // Aggregator aggregates, snapshots and assigns priority to an associated value. 67 // - V is the value type used as a pointer 68 // - V may be a thread-safe object whose values change in real-time 69 // - P is the priority type descending order, ie. Integer Floating-Point string 70 type Aggregator[V any, P constraints.Ordered] interface { 71 // Value returns the value object this Aggregator is associated with 72 // - the Value method is used by consumers of the AggregatingPriorityQueue 73 Value() (valuep *V) 74 // Aggregate aggregates and snapshots data values from the value object. 75 // - Aggregate is invoked outside of AggregatingPriorityQueue 76 Aggregate() 77 // Priority returns the current priority for the associated value 78 // - this priority is cached by AggregatePriority 79 Priority() (priority P) 80 } 81 82 // AssignedPriority contains the assigned priority for a priority-queue element 83 // - V is the element value type whose pointer-value provides identity 84 // - P is the priority, a descending-ordered type: Integer Floating-Point string 85 type AssignedPriority[V any, P constraints.Ordered] interface { 86 SetPriority(priority P) 87 }