network: Documented, simplified and cleaner eachBin function in pot.go

[kortatu]

I've tried to make EachBin function more clear to developers. It used to have this signature:

func (t *Pot) EachBin(val Val, pof Pof, po int, f func(int, int, func(func(val Val) bool) bool) bool) {

...and almost no documentation. It was difficult to understand what was the purpose of each of the three annonymous function parameters of EachBin.

I've created several abstractions to try to express better the behaviour of these iterators.

There is a new type ValConsumer with signature: type ValConsumer func(Val) bool that consumes a value Val and returns whether the caller wants to consume more values.
This consumer can be generalized so I created also BinConsumer with similar signature:
type BinConsumer func(bin *Bin) bool. Unsurprisingly, this function consumes a Bin and returns whether to continue consuming Bins or stop.

There is also a ValIterator function type:
type ValIterator func(ValConsumer) bool
that completes the abstraction of iterators. An iterator of type T takes a consumer of type T (ValConsumer in this case) and starts iterating T elements. The iterator returns a boolean signaling the last value returned by the last consume function. The ValIterator in our case is responsible of iterating Val elements inside a Bin.
Finally, Bin is just a struct with the information provided to a BinConsumer, its ProximityOrder, its Size and the ValIterator to traverse all its Val elements:

type Bin struct {
	ProximityOrder int
	Size           int
	ValIterator    ValIterator
}

With this new types, the signature of EachBin now is:

func (t *Pot) EachBin(pivotVal Val, pof Pof, minProximityOrder int, binConsumer BinConsumer) {

I also renamed the parameters to express their use.

[zelig]

very nice refactor.
NOTE that pot will be rewritten very soon. Dont spend too much time deciphering this

[nolash]

if -> it

[nolash]

Usually is the pin of a pot

I am not sure I understand what you mean here.

[kortatu]

Almost all uses of EachBin will use k.base as pivotVal, so it will be the node address and the "pin" of the pot.
In that situation eachBin is just traversing the bins from less po to more po and finally consuming the pin of the pot.

[nolash]

Ok. But I am unsure about the wording here. "Usually the value passed to the ValConsumer is the pin"

If we want a tutorial-ish overview of the use cases in the comment, maybe they should be in bullet points and give a bit more context. What do you think?

[kortatu]

In fact I think I'm going to change it. The last val consumed will be always the pivot value.

[nolash]

Please consider using a different variable name than the package name

[kortatu]

very nice refactor.
NOTE that pot will be rewritten very soon. Dont spend too much time deciphering this

Ok, let the rewrite of pot have a better guideline for rewrite EachBin function

[nolash]

rewritten very soon

My bet is it won't be THAT soon ;)