package unique

Import Path
	unique (on go.dev)

Dependency Relation
	imports 7 packages, and imported by one package

Involved Source Files

	    clone.go
	  d doc.go
		The unique package provides facilities for canonicalizing ("interning")
		comparable values.

	    handle.go
Package-Level Type Names (total 3, in which 1 is exported)

	/* sort exporteds by: alphabet | popularity */
	 type Handle[T] (struct)

		Type Parameters:
			T: comparable

		Handle is a globally unique identity for some value of type T.
		
		Two handles compare equal exactly if the two values used to create the handles
		would have also compared equal. The comparison of two handles is trivial and
		typically much more efficient than comparing the values used to create them.

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			value *T
		Methods (only one, which is exported)
			( Handle[T]) Value() T
				Value returns a shallow copy of the T value that produced the Handle.

		As Outputs Of (at least one exported)
			func Make[T](value T) Handle[T]
		As Types Of (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			  var net/netip.z0 unique.Handle[addrDetail]
			  var net/netip.z4 unique.Handle[...]
			  var net/netip.z6noz unique.Handle[...]

	/* 2 unexporteds ... *//* 2 unexporteds: */
	 type cloneSeq (struct)
		cloneSeq describes how to clone a value of a particular type.

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			stringOffsets []uintptr
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func makeCloneSeq(typ *abi.Type) cloneSeq
		As Inputs Of (at least 3, none are exported)
			/* 3+ unexporteds ... *//* 3+ unexporteds: */
			func buildArrayCloneSeq(typ *abi.Type, seq *cloneSeq, baseOffset uintptr)
			func buildStructCloneSeq(typ *abi.Type, seq *cloneSeq, baseOffset uintptr)
			func clone[T](value T, seq *cloneSeq) T
		As Types Of (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			  var singleStringClone

	 type uniqueMap[T] (struct)

		Type Parameters:
			T: comparable

		Fields (total 8, in which 1 is exported)
			HashTrieMap *concurrent.HashTrieMap[T, weak.Pointer[T]]
			/* 7 unexporteds ... *//* 7 unexporteds: */
			cloneSeq cloneSeq
			cloneSeq.stringOffsets []uintptr
			HashTrieMap.keyEqual concurrent.equalFunc
			HashTrieMap.keyHash concurrent.hashFunc
			HashTrieMap.root *concurrent.indirect[T, weak.Pointer[T]]
			HashTrieMap.seed uintptr
			HashTrieMap.valEqual concurrent.equalFunc
		Methods (total 6, in which 4 are exported)
			( uniqueMap[K, V]) All() func(yield func(T, weak.Pointer[T]) bool)
				All returns an iter.Seq2 that produces all key-value pairs in the map.
				The enumeration does not represent any consistent snapshot of the map,
				but is guaranteed to visit each unique key-value pair only once. It is
				safe to operate on the tree during iteration. No particular enumeration
				order is guaranteed.

			( uniqueMap[K, V]) CompareAndDelete(key T, old weak.Pointer[T]) (deleted bool)
				CompareAndDelete deletes the entry for key if its value is equal to old.
				
				If there is no current value for key in the map, CompareAndDelete returns false
				(even if the old value is the nil interface value).

			( uniqueMap[K, V]) Load(key T) (value weak.Pointer[T], ok bool)
				Load returns the value stored in the map for a key, or nil if no
				value is present.
				The ok result indicates whether value was found in the map.

			( uniqueMap[K, V]) LoadOrStore(key T, value weak.Pointer[T]) (result weak.Pointer[T], loaded bool)
				LoadOrStore returns the existing value for the key if present.
				Otherwise, it stores and returns the given value.
				The loaded result is true if the value was loaded, false if stored.

			/* 2 unexporteds ... *//* 2 unexporteds: */
			( uniqueMap[K, V]) expand(oldEntry, newEntry *concurrent.entry[T, weak.Pointer[T]], newHash uintptr, hashShift uint, parent *concurrent.indirect[T, weak.Pointer[T]]) *concurrent.node[T, weak.Pointer[T]]
				expand takes oldEntry and newEntry whose hashes conflict from bit 64 down to hashShift and
				produces a subtree of indirect nodes to hold the two new entries.

			( uniqueMap[K, V]) iter(i *concurrent.indirect[T, weak.Pointer[T]], yield func(key T, value weak.Pointer[T]) bool) bool
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func addUniqueMap[T](typ *abi.Type) *uniqueMap[T]


Package-Level Functions (total 8, in which 1 is exported)

	 func Make[T](value T) Handle[T]

		Type Parameters:
			T: comparable

		Make returns a globally unique handle for a value of type T. Handles
		are equal if and only if the values used to produce them are equal.

	/* 7 unexporteds ... *//* 7 unexporteds: */
	 func addUniqueMap[T](typ *abi.Type) *uniqueMap[T]

		Type Parameters:
			T: comparable

	 func buildArrayCloneSeq(typ *abi.Type, seq *cloneSeq, baseOffset uintptr)
		buildArrayCloneSeq populates a cloneSeq for an abi.Type that has Kind abi.Array.

	 func buildStructCloneSeq(typ *abi.Type, seq *cloneSeq, baseOffset uintptr)
		buildStructCloneSeq populates a cloneSeq for an abi.Type that has Kind abi.Struct.

	 func clone[T](value T, seq *cloneSeq) T

		Type Parameters:
			T: comparable

		clone makes a copy of value, and may update string values found in value
		with a cloned version of those strings. The purpose of explicitly cloning
		strings is to avoid accidentally giving a large string a long lifetime.
		
		Note that this will clone strings in structs and arrays found in value,
		and will clone value if it itself is a string. It will not, however, clone
		strings if value is of interface or slice type (that is, found via an
		indirection).

	 func makeCloneSeq(typ *abi.Type) cloneSeq
		makeCloneSeq creates a cloneSeq for a type.

	 func registerCleanup()
		startBackgroundCleanup sets up a background goroutine to occasionally call cleanupFuncs.

	 func runtime_registerUniqueMapCleanup(cleanup func())
Package-Level Variables (total 7, none are exported)

	/* 7 unexporteds ... *//* 7 unexporteds: */
	  var cleanupFuncs []func()
	  var cleanupFuncsMu sync.Mutex
	  var cleanupMu sync.Mutex
		cleanupFuncs are functions that clean up dead weak pointers in type-specific
		maps in uniqueMaps. We express cleanup this way because there's no way to iterate
		over the sync.Map and call functions on the type-specific data structures otherwise.
		These cleanup funcs each close over one of these type-specific maps.
		
		cleanupMu protects cleanupNotify and is held across the entire cleanup. Used for testing.
		cleanupNotify is a test-only mechanism that allow tests to wait for the cleanup to run.

	  var cleanupNotify []func() // One-time notifications when cleanups finish.
	  var setupMake sync.Once
		setupMake is used to perform initial setup for unique.Make.

	  var singleStringClone cloneSeq
		singleStringClone describes how to clone a single string.

	  var uniqueMaps *concurrent.HashTrieMap[...] // any is always a *uniqueMap[T].
		uniqueMaps is an index of type-specific concurrent maps used for unique.Make.
		
		The two-level map might seem odd at first since the HashTrieMap could have "any"
		as its key type, but the issue is escape analysis. We do not want to force lookups
		to escape the argument, and using a type-specific map allows us to avoid that where
		possible (for example, for strings and plain-ol'-data structs). We also get the
		benefit of not cramming every different type into a single map, but that's certainly
		not enough to outweigh the cost of two map lookups. What is worth it though, is saving
		on those allocations.

The pages are generated with Golds v0.7.6. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.