collection: document garbage collection behaviour of *Map and *Program

Since this behaviour can be surprising, especially when handling prog arrays,
document the recommended usage on functions returning Collection/Map/Program.

Signed-off-by: Timo Beckers <timo@isovalent.com>

collection.go

@@ -191,6 +191,9 @@ func (cs *CollectionSpec) Assign(to interface{}) error {
 // LoadAndAssign loads Maps and Programs into the kernel and assigns them
 // to a struct.
 //
+// Omitting Map/Program.Close() during application shutdown is an error.
+// See the package documentation for details around Map and Program lifecycle.
+//
 // This function is a shortcut to manually checking the presence
 // of maps and programs in a CollectionSpec. Consider using bpf2go
 // if this sounds useful.
@@ -273,12 +276,20 @@ type Collection struct {
 	Maps     map[string]*Map
 }
 
-// NewCollection creates a Collection from a specification.
+// NewCollection creates a Collection from the given spec, creating and
+// loading its declared resources into the kernel.
+//
+// Omitting Collection.Close() during application shutdown is an error.
+// See the package documentation for details around Map and Program lifecycle.
 func NewCollection(spec *CollectionSpec) (*Collection, error) {
 	return NewCollectionWithOptions(spec, CollectionOptions{})
 }
 
-// NewCollectionWithOptions creates a Collection from a specification.
+// NewCollectionWithOptions creates a Collection from the given spec using
+// options, creating and loading its declared resources into the kernel.
+//
+// Omitting Collection.Close() during application shutdown is an error.
+// See the package documentation for details around Map and Program lifecycle.
 func NewCollectionWithOptions(spec *CollectionSpec, opts CollectionOptions) (*Collection, error) {
 	loader := newCollectionLoader(spec, &opts)
 	defer loader.cleanup()
@@ -531,7 +542,11 @@ func (cl *collectionLoader) populateMaps() error {
 	return nil
 }
 
-// LoadCollection parses an object file and converts it to a collection.
+// LoadCollection parses an object file and creates and loads its declared
+// resources into the kernel, returning a Collection.
+//
+// Omitting Collection.Close() during application shutdown is an error.
+// See the package documentation for details around Map and Program lifecycle.
 func LoadCollection(file string) (*Collection, error) {
 	spec, err := LoadCollectionSpec(file)
 	if err != nil {

doc.go

@@ -13,4 +13,13 @@
 // your application as any other resource.
 //
 // Use the link subpackage to attach a loaded program to a hook in the kernel.
+//
+// Note that losing all references to Map and Program resources will cause
+// their underlying file descriptors to be closed, potentially removing those
+// objects from the kernel. Always retain a reference by e.g. deferring a
+// Close() of a Collection or LoadAndAssign object until application exit.
+//
+// Special care needs to be taken when handling maps of type ProgramArray,
+// as the kernel erases its contents when the last userspace or bpffs
+// reference disappears, regardless of the map being in active use.
 package ebpf