parli

Documentation

Overview

Package parli provides certain interface declarations.

Index

• Constants
• type Ordered
• type OrderedPointers
• type Slice
• type Socket
• type ThreadSafeMap

Constants

const (
	MapDeleteWithZeroValue = true
	MapClearUsingRange     = true
)

Types

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.
	//   - 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)
	//	- if useZeroValue present and parli.MapDeleteWithZeroValue or true,
	//		the deleted value is fiorst assigned the zero-value
	Delete(key K, useZeroValue ...bool)
	// Clear empties the map
	//	- if useRange is present and parli.MapClearUsingRange or true,
	//		delete using range operations setting each item to zero-value
	//	- otherwise, clear by replacing with new map
	Clear(useRange ...bool)
	// Length returns the number of mappings
	Length() (length int)
	// Clone returns a shallow clone of the map
	Clone() (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.

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