parli

Documentation

Index

• type AggregatePriority
• type AggregatingPriorityQueue
• type Aggregator
• type AssignedPriority
• type Ordered
• type OrderedPointers
• type PriorityQueue
• type Slice
• type Socket
• type ThreadSafeMap

Types

type AggregatePriority

type AggregatePriority[V any, P constraints.Ordered] interface {
	// Aggregator returns the aggregator associated with this AggregatePriority
	Aggregator() (aggregator Aggregator[V, P])
	// Update caches the current priority from the aggregator
	Update()
	// Priority returns the effective cached priority
	//	- Priority is used by consumers of the AggregatingPriorityQueue
	CachedPriority() (priority P)
	// Index indicates insertion order
	//	- used for ordering elements of equal priority
	Index() (index int)
}

AggregatePriority caches the priority value from an aggregator for priority.

• V is the value type used as a pointer
• P is the priority type descending order, ie. Integer Floating-Point string

type AggregatingPriorityQueue

type AggregatingPriorityQueue[V any, P constraints.Ordered] interface {
	// Get retrieves a possible value container associated with valuep
	Get(valuep *V) (aggregator Aggregator[V, P], ok bool)
	// Put stores a new value container associated with valuep
	//   - the valuep is asusmed to not have a node in the queue
	Put(valuep *V, aggregator Aggregator[V, P])
	// Update re-prioritizes a value
	Update(valuep *V)
	// Clear empties the priority queue. The hashmap is left intact.
	Clear()
	// List returns the first n or default all values by pirority
	List(n ...int) (aggregatorQueue []AggregatePriority[V, P])
}

pmaps.AggregatingPriorityQueue uses cached priority obtained from Aggregators that operates on the values outside of the AggregatingPriorityQueue.

• the Update method reprioritizes an updated value element

type Aggregator

type Aggregator[V any, P constraints.Ordered] interface {
	// Value returns the value object this Aggregator is associated with
	//	- the Value method is used by consumers of the AggregatingPriorityQueue
	Value() (valuep *V)
	// Aggregate aggregates and snapshots data values from the value object.
	//	- Aggregate is invoked outside of AggregatingPriorityQueue
	Aggregate()
	// Priority returns the current priority for the associated value
	//	- this priority is cached by AggregatePriority
	Priority() (priority P)
}

Aggregator aggregates, snapshots and assigns priority to an associated value.

• V is the value type used as a pointer
• V may be a thread-safe object whose values change in real-time
• P is the priority type descending order, ie. Integer Floating-Point string

type AssignedPriority

type AssignedPriority[V any, P constraints.Ordered] interface {
	SetPriority(priority P)
}

AssignedPriority contains the assigned priority for a priority-queue element

• V is the element value type whose pointer-value provides identity
• P is the priority, a descending-ordered type: Integer Floating-Point string

type Ordered

type Ordered[E any] interface {
	Slice[E] // Element() Length() Clear() List()
	// Insert adds an element to the ordered slice.
	// The implementation may allow duplicates.
	Insert(element E)
	// Delete removes an element from the ordered slice.
	// If the ordered slice does not contain element, the slice is not changed.
	Delete(element E)
	// Index returns index of the first occurrence of element in the ordered slice
	// or -1 if element is not in the slice.
	Index(element E) (index int)
	// Clone returns a clone of the ordered slice
	Clone() (ordered Ordered[E])
}

Ordered[E any] is an ordered list of values.

• Ordered should be used when E is interface type or a small-sized value.
• pslices.NewOrdered[E constraints.Ordered]() instantiates for comparable types, ie. not func map slice
• pslices.NewOrderedAny[E any](cmp func(a, b E) (result int)) instantiates for any type or for custom sort order
• pslices.NewOrderedPointers[E constraints.Ordered]() orders pointer to value, to be used for large structs or order of in-place data
• those list implementations have Index O(log n)

type OrderedPointers

type OrderedPointers[E any] interface {
	Ordered[*E]
}

OrderedPointers[E any] is an ordered list of pointers sorted by the referenced values. OrderedPointers should be used when E is a large struct. pslices.NewOrderedPointers[E constraints.Ordered]() instantiates for pointers to comparable types, ie. not func slice map. pslices.NewOrderedAny instantiates for pointers to any type or for custom sort orders.

type PriorityQueue

type PriorityQueue[V any, P constraints.Ordered] interface {
	// AddOrUpdate adds a new value to the prioirty queue or updates the priority of a value
	// that has changed.
	AddOrUpdate(value *V)
	// List returns the first n or default all values by priority
	List(n ...int) (valueQueue []*V)
}

PriorityQueue is a pointer-identity-to-value map of updatable values traversable by rank.

• PriorityQueue operates directly on value by caching priority from the pritority function.
• the AddOrUpdate method reprioritizes an updated value element
• V is a value reference composite type that is comparable, ie. not slice map function. Preferrably, V is interface or pointer to struct type.
• P is an ordered type such as Integer Floating-Point or string, used to rank the V values
• values are added or updated using AddOrUpdate method distinguished by (computer science) identity
• if the same comparable value V is added again, that value is re-ranked
• priority P is computed from a value V using the priorityFunc function. The piority function may be examining field values of a struct
• values can have the same rank. If they do, equal rank is provided in insertion order
• pmaps.NewPriorityQueue[V any, P constraints.Ordered]
• pmaps.NewRankingThreadSafe[V comparable, R constraints.Ordered]( ranker func(value *V) (rank R)))

type Slice

type Slice[E any] interface {
	// Element returns element by index.
	// if index is negative or the length of the slice or larger, the E zero-value is returned.
	Element(index int) (element E)
	// SubSlice returns a multiple-element sub-slice, not a clone
	//	index0 and index1 aree adjusted to legal values
	SubSlice(index0, index1 int) (elements []E)
	// SetElement updates single element by index
	//	- slice is extended if too short
	SetElement(index int, element E)
	// Append adds element at end
	Append(slice []E)
	// DeleteIndex removes elements by index
	//	- index1 default is slice length
	DeleteIndex(index0 int, index1 ...int)
	// Length returns number of elements in the slice
	Length() (length int)
	// Cap returns slice capacity
	Cap() (capacity int)
	// Clear empties the ordered slice
	Clear()
	// List returns a clone of the internal slice
	List(n ...int) (list []E)
}

Slice is a reusable unordered slice

• functions by index that apply to unordered slice
• embedded interface for slice interface types

type Socket

type Socket interface {
	// Local is the near ip address and port
	//	- local IP is 0.0.0.0 or :: for wildcard bind
	//	- port is 0 for 24% sendto udp client sockets, which is also possible for tcp
	//	- port is 0 for non-port protocols such as icmp igmp
	//	- broadcast and multicast udp receive is custom
	Local() (local netip.AddrPort)
	// Remote is the far IP address and port
	//	- 0.0.0.0:0 or :::0 for listening ports
	Remote() (remote netip.AddrPort)
	// Protocol is the IP protocol. Protocol is always present
	Protocol() (protocol iana.Protocol)
	// AddressFamily is the type of address used
	//	- It is undefined 0 for 2% few dns connections
	//	- platforms may have proprietary handling of ip46 ports, ie. listening for both IPv4 and IPv6
	AddressFamily() (addressFamily iana.AddressFamily)
	// InternetSocket is a near-end quasi-unique identifier
	//	- opaque identifier based on IP, port and protocol
	//	- shared ports, sendto udp clients or non-port protocols may not be unique
	InternetSocket() (internetSocket iana.InternetSocket)
	//	Pid is the process identifier for the process using the Socket
	//	- Pid is undefined 0 for 26% tcp ports in LISTEN, TIME_WAIT or CLOSED
	Pid() (pid pids.Pid)
}

Socket is a representation of a network connection

• may be inbound or outbound
• may be for all interfaces
• only exists for IP protocols
• may be raw socket

type ThreadSafeMap

type ThreadSafeMap[K comparable, V any] interface {
	// Get returns the value mapped by key or the V zero-value otherwise.
	//   - the ok return value is true if a mapping was found.
	//   - O(1)
	Get(key K) (value V, ok bool)
	// GetOrCreate returns an item from the map if it exists otherwise creates it.
	//   - newV or makeV are invoked in the critical section, ie. these functions
	//     may not access the map or deadlock
	//   - if a key is mapped, its value is returned
	//   - otherwise, if newV and makeV are both nil, nil is returned.
	//   - otherwise, if newV is present, it is invoked to return a pointer ot a value.
	//     A nil return value from newV causes panic. A new mapping is created using
	//     the value pointed to by the newV return value.
	//   - otherwise, a mapping is created using whatever makeV returns
	//	- newV and makeV may not access the map.
	//		The map’s write lock is held during their execution
	//	- GetOrCreate is an atomic, thread-safe operation
	//   - value insert is O(log n)
	GetOrCreate(
		key K,
		newV func() (value *V),
		makeV func() (value V),
	) (value V, ok bool)
	// Put saves or replaces a mapping
	Put(key K, value V)
	// Putif is conditional Put depending on the return value from the putIf function.
	//	- if key does not exist in the map, the put is carried out and wasNewKey is true
	//	- if key exists and putIf is nil or returns true, the put is carried out and wasNewKey is false
	//	- if key exists and putIf returns false, the put is not carried out and wasNewKey is false
	//   - during PutIf, the map cannot be accessed and the map’s write-lock is held
	//	- PutIf is an atomic, thread-safe operation
	PutIf(key K, value V, putIf func(value V) (doPut bool)) (wasNewKey bool)
	// Delete removes mapping using key K.
	//   - if key K is not mapped, the map is unchanged.
	//   - O(log n)
	Delete(key K)
	// Clear empties the map
	Clear()
	// Length returns the number of mappings
	Length() (length int)
	// Clone returns a shallow clone of the map
	Clone() (clone ThreadSafeMap[K, V])
	// Swap replaces the map with otherMap and returns the current map in previousMap
	//	- if otherMap is not initialized RWMap, no swap takes place and previousMap is nil
	//	- Swap is an atomic, thread-safe operation
	Swap(otherMap ThreadSafeMap[K, V]) (previousMap ThreadSafeMap[K, V])
	// List provides the mapped values, undefined ordering
	//   - O(n)
	List() (list []V)
}

ThreadSafeMap is a one-liner thread-safe mapping.

• pmaps.NewRWMap[K comparable, V any]()