parli

Documentation

Overview

Package parli provides certain interface declarations.

Index

• type ClearMethod
• type DeleteMethod
• type GoMap
• type Map
• type Ordered
• type OrderedPointers
• type Slice
• type Socket
• type ThreadSafeMap
• type ValueOrderedMap

Types

type ClearMethod

type ClearMethod bool

whether map clear uses range to clear the map

• MapClearUsingRange

const (
	// [ThreadSafeMap.Clear] clear the map by ranging all mappings
	//	- default is to clear the map by replacing it with a created map
	//	- — this prevents temporaty mwemory leak from large allocated
	//		structures
	MapClearUsingRange ClearMethod = true
)

type DeleteMethod

type DeleteMethod bool

whether map delete uses zero-value to avoid temporary memory leaks

• MapDeleteWithZeroValue

const (
	// [ThreadSafeMap.Delete] deleted mappings are first written with
	//	zero-value to prevent temporary memory leaks from pointers in value
	MapDeleteWithZeroValue DeleteMethod = true
)

type GoMap

type GoMap[K comparable, V any] interface {
	// Get returns a possibly mapped value mapped by key or the V zero-value otherwise
	//   - key: the key of the mapping
	//   - value: the value mapped or V zero-value
	//   - hasValue true: value is valid, the mapping did exist
	//   - hasValue false: value is zero-value, the mapping did not exist
	//   - amortized O(1) for Go map implementations
	Get(key K) (value V, hasValue bool)
	// Put creates or replaces a mapping
	Put(key K, value V)
	// Delete removes mapping for key
	//   - if key is not mapped, the map is unchanged
	//	- may zero-set the mapping to avoid temporary
	//		memory leaks from retained V values
	//   - O(log n) for Go map implementations
	Delete(key K)
	// Length returns the number of mappings
	Length() (length int)
	// Range traverses map bindings
	//   - iterates over map until rangeFunc returns false
	//   - order is undefined
	//   - similar to [sync.Map.Range] func (*sync.Map).Range(f func(key any, value any) bool)
	Range(rangeFunc func(key K, value V) (keepGoing bool)) (rangedAll bool)
}

GoMap is a reusable promotable Go map

• 5 native Go Map functions: Get Put Delete Length Range
• GoMap is a base interface implemented as Map and other derived interfaces

type Map

type Map[K comparable, V any] interface {
	// Get Put Delete Length Range
	GoMap[K, V]
	// Clear empties the map
	//   - may clear by re-creating the map
	//   - may clear by ranging and deleting all keys,
	//     retaining the allocated map-size
	Clear()
	// Clone returns a shallow clone of the map
	//	- goMap: optional pointer to receiving Go map instance
	//	- — Clone returns nil
	Clone(goMap ...*map[K]V) (clone Map[K, V])
}

Map is a reusable promotable Go map

• 5 native Go Map functions: Get Put Delete Length Range
• 2 convenience functions: Clear Clone
• implemented by github.com/haraldrudell/parl/pmaps/pmaps2/Map

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 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
	//	- key: the mappin gkey whose value to retrieve
	//	- value: a V or V zero-value
	//	- hasValue true: mapping existed, value is valid
	//	- hasValue false: a mapping did not exist, value is zero-value
	//   - Go map O(1), RWMap uses read lock
	Get(key K) (value V, hasValue bool)
	// GetOrCreate returns an item from the map if it exists otherwise creates it.
	//   - 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 to 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 makeV return value
	//	- newV and makeV may not access the map.
	//		The map’s write lock is held during their execution
	//	- newV pointer facilitates saving a copy of existing value in the map using single copy operation
	//	- makeV facilitates saving value without allocation
	//	- GetOrCreate is an atomic, thread-safe operation
	//	- GetOrCreate uses write lock, not read lock like Get
	//   - 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 of key K
	//   - key: mapping key to  delete.
	//		If K is not mapped, the map is unchanged
	//	- useZeroValue [MapDeleteWithZeroValue]: the deleted value is first assigned the zero-value.
	//		If V contains pointers, zero-value prevents temporary memory leaks
	//	- —
	//   - Go map implementations O(log n)
	Delete(key K, useZeroValue ...DeleteMethod)
	// Clear empties the map
	//	- useRange [MapClearUsingRange]: delete using range operations setting each item to zero-value
	//	- useRange missing: clear by replacing with new map
	Clear(useRange ...ClearMethod)
	// Length returns the number of mappings
	Length() (length int)
	// Clone returns a shallow clone of the map
	//	- if goMap is present and non-nil, it receives a Go-map clone. return value is then nil
	Clone(goMap ...*map[K]V) (clone ThreadSafeMap[K, V])
	// List provides the mapped values, undefined ordering
	//   - O(n)
	List(n ...int) (list []V)
}

ThreadSafeMap is a one-liner thread-safe mapping

• implementation based on sync.RWMutex is github.com/haraldrudell/parl/pmaps.RWMap

type ValueOrderedMap

type ValueOrderedMap[K comparable, V any] interface {
	// Get Put Delete Length Range
	GoMap[K, V]
	// Clear empties the map
	//   - may clear by re-creating the map
	//   - may clear by ranging and deleting all keys,
	//     retaining the allocated map-size
	Clear()
	// Clone returns a shallow clone of the map
	//	- goMap: optional pointer to receiving Go map instance
	//	- — Clone returns nil
	Clone(goMap ...*map[K]V) (clone ValueOrderedMap[K, V])
	// List provides mapped values in order
	//   - n zero, missing: list contains all items
	//   - n non-zero: list contains zero to n items capped by map length
	List(n ...int) (list []V)
}

ValueOrderedMap is a mapping whose values are provided in custom order

• implemented by github.com/haraldrudell/parl/omaps/ValueOrderedMap