See commit comments for details.

Add new batched iterator type in pkg/bpf:

This is intended to provide a general approach to iterating maps using the "batched" API, and replace existing bespoke implementations in ctmap/nat to use the one generic approach.

Follow up work

This PR will not change pkg/maps/ctmap to use this as @ysksuzuki is currently working on refactoring the ctmap gc code, which would likely cause large conflicts - so that will be a follow up to that work being done.

// NewBatchIterator returns a typed wrapper for *Map that allows for
// iterating (i.e. "dumping") the map using the bpf batch api.
//
// Unlike the general *Map dump functions, this must reads into slices of
// a concrete type (such as struct, or other scalar type), rather than into
// pointers. This is because there is currently no safe way to allocate a
// contiguous slice of key/value elements from either the underlying generic
// pointer types or from MapKey/MapValue interface types.
//
// This means that attempting to use the pointer types that implement
// MapKey/MapValue will fail upon iteration (via the Err() function).
//
// Example usage:
//
//	m := NewMap("cilium_test",
//		ebpf.Hash,
//		&TestKey{}, 	// *TestKey implements MapKey.
//		&TestValue{}, 	// *TestValue implements MapValue.
//		mapSize,
//		BPF_F_NO_PREALLOC,
//	)
//
//	// Note: TestKey & TestValue are not pointer types!
//	iter := NewBatchIterator[TestKey, TestValue](m)
//	for k, v := range iter {
//		// ...
//	}
//
// Following iteration, any unresolved errors encountered when iterating
// the bpf map can be accessed via the Err() function.

Design considerations

1. Using Generics: Most Cilium functions that abstract bpf map operations rely on the MapKey and MapValue interfaces, in particular the respective New() MapKey & New() MapValue interface functions which allow allocation of a key/value pointer type in an opaque manner. For batched operations this doesn't work as we need to be able to allocate contiguous, non-indirect, slices of objects which are passed to the batched bpf syscalls for processing. Thus this is done with a generic wrapper type, which is able to do such an allocations (i.e. make([]T, batchSize)). The tradeoff is that, going back to the first problem, the generic type must not be a pointer/interface type, so even if the implentation of Map{Key,Value} is using the pointer handle for a type (i.e. is implemented with func (k *someKeyType) Map() bpf.MapKey {...}), we still need to use the serial struct type in this situation (i.e. NewBatchIterator[someKeyType, someValueType]). Failing to do so will result in a runtime error.

2. Error Handling: The benefits of returning a seq.Iter2 type is that this will compose nicely with loops and other functional list operations in the future. The downside is that batched iteration can fail, thus we need some kind of error collection mechanism. With this I've opted to collect Errors with the Err() function. Practically, this means that we need to actually use a iterator handle instead of just doing it purely functionally.

Use batched iteration for ctmap GC to improve performance

note: I'm using pkg/bpf/ as a staging ground for hammering out a good API for a batched iterator, a follow up will be to open a PR to add this functionality in cilium/ebpf and then use that.