[ready for review] btreeg: add support for no alloc iter

[arjunnair1997]

This pr introduces the following API:

// ReleaseReuseable is the same as Release, but it preserves the iterator stack
// so that the iterator can be reused using Init without allocating.
func (iter *IterG[T]) ReleaseReuseable() {
	if iter.tr == nil {
		return
	}
	if iter.locked {
		iter.tr.unlock(iter.mut)
		iter.locked = false
	}

	// Preserve the backing memory for the stack, so that the iterator can be re-used without
	// allocating.
	iter.stack = iter.stack[:0]
	iter.tr = nil
}

// Init is used to initialize an existing iterator with a new tree. ReleaseReusable must've
// been called on the iterator before re-using it using Init.
func (iter *IterG[T]) Init(tr *BTreeG[T], mut bool) {
	iter.tr = tr
	iter.mut = mut

	iter.locked = tr.lock(iter.mut)
	if iter.stack == nil {
		iter.stack = iter.stack0[:0]
	} else {
		iter.stack = iter.stack[:0]
	}

	iter.seeked = false
	iter.atstart = false
	iter.atend = false
	iter.item = tr.empty
}

First, an iterator is created using the BtreeG.Iter or IterMut method. Then, the iterator can be re-used by first calling ReleaseReusable, and then calling Init.

This prevents two types of allocations:

1. To grow the iter.stack slice.
2. The iterator can escape to the heap as included in the benchmark.

[tidwall]

Is the goal here to have a zero alloc iterator?
Changing the Init behavior, like you've shown, does omits the heap escape, but there will still be escapes in the future with the cursor functions First/Last/Next/Prev.

[arjunnair1997]

Is the goal here to have a zero alloc iterator? Changing the Init behavior, like you've shown, does omits the heap escape, but there will still be escapes in the future with the cursor functions First/Last/Next/Prev.

This is the only alloc which is significant enough to show up in our profiles. I'm just using a seek + next.

[tidwall]

Can you provide a little more info about what you are seeing?
Perhaps some code to reproduce the issue?
I'm running with and without Iter() and IterNoAlloc() and I'm not seeing any difference.

[tidwall]

It just occurred to me, but if you are only using Seek and Next, you may want to consider using the Ascend function. It has a much lower footprint, doesn't touch the heap, and is generally faster than using the Iter functions.

[arjunnair1997]

@tidwall

I can't use ascend as I need to do a specific kind of iteration. Let's say the keys are k1 < k2 < k3 < k4. If I have have a pivot key k_x such that k_2 < k_x < k_3, then I need my ascension to start from k_2 and not k_3. Ascend would start the iteration at k_3. Right now, we use Descend + Ascend combo for this, but that's too expensive. First descend to find the first key <= k_x, and then Ascend using k_x as pivot.

I don't want to use an iterator either, I'd rather just use a function like ascend which starts iteration one key prior the first key which is >=.

Basically what I want is Descend + scan forward which does a single seek to find the item to start the scan at(k_2 in the above example), and the scans forward like ascend. I can implement this if you're open to it.

What do you think?

[tidwall]

So perhaps functions similar to Ascend and Descend, that starts at a pivot, but allows for moving forward and backwards like cursor? That's interesting actually.

I'm seeing something like: (not sure of the name yet)

const (
    Stop Action = iota
    Prev
    Next
)

func (tr *BTree[T]) IterAscend(pivot T, iter(item T) Action)
func (tr *BTree[T]) IterDescend(pivot T, iter(item T) Action)
func (tr *BTree[T]) IterScan(iter(item T) Action)
func (tr *BTree[T]) IterReverse(iter(item T) Action)

These could work like Ascend, Descend, Scan, and Reverse, but instead or returning true or false, you can return Stop, Next, or Prev.

This will allow to start at any pivot and change direction on the fly.

[arjunnair1997]

@tidwall Sorry about the delay.

I've made a lot of changes to this pr, it's a lot different from what we were discussing. I've included a benchmark which shows the allocation with the regular iterators. Then, I've introduced a new api to use the iterator without any allocations.

Please take a look whenever you get the chance. The changes and the reasoning is described here: #52 (comment)

I like the idea you mentioned here: #52 (comment), I've never seen an API like that before and it's pretty interesting, but just using the existing iterator is sufficient for our use case.

[tidwall]

Overall LGTM.

Though I am wondering if we can simply replace the existing iter.Release() with your new iter.ReleaseReusable()?
That way we have a one Release() function. Not sure if there's a side effect I'm not seeing.

[arjunnair1997]

@tidwall Please take a look. Re-using Release, and made the re-use of the iterator safer by zeroing out memory.

[tidwall]

Looks good!