Netmap: head vs cur vs tail?

[Matthew P. Grosvenor]

Hi all,
I’m trying to understand how to use the netmap framework, specifically how the head, tail and current “pointers” interact with each other. 

Looking in man NETMAP(4) (http://www.freebsd.org/cgi/man.cgi?query=netmap&sektion=4) under data structures, struct netmap_ring	 it says: "  contains the index of he current read or write slot (cur), “. In the example code, the following pattern is used: 

 	i = ring->cur;
	...
	ring->cur = NETMAP_RING_NEXT(ring, i);

However, in the example that ships with the netmap source (https://code.google.com/p/netmap/source/browse/examples/bridge.c#72 & https://code.google.com/p/netmap/source/browse/examples/pkt-gen.c#660) the following pattern is used: 

	j = rxring->cur; 
	while(…){
		j = nm_ring_next(rxring, j);
	…
	}
	rxring->head = rxring->cur = j;

So the obvious question is, what is the relationship between head and current? Do I believe the man page (and man page example) that head is not necessary, or do I believe the example code that head is necessary and should be set to the same value as current? And if so, what is the point of head? And why is it updated outside of the loop in both of the examples? 

At a high level, I’m looking for a better understanding of what head, tail and current mean and how they affect the processing of rings. 

Cheers,
Matt