Context-aware element iterators

[sandro-elsweijer]

When introducing element iterators, we can give them context-awareness, so that they add functionality to the elements.

What do I mean by that?

It would be nice to do this

for (auto& element: forest)
{
  element.get_level()
}

instead of this:

/* Get the scheme used by this forest. */
const t8_scheme *scheme = t8_forest_get_scheme(forest);
/* Loop over each tree in the forest */
for (t8_locidx_t itree = 0; itree < num_local_trees; ++itree){
  /* Get the number of elements in the tree itree */
  const t8_locidx_t num_elems = t8_forest_get_tree_num_elements (forest, itree);
  /* Get the class of the tree. */
  const t8_eclass_t tree_class = t8_forest_get_tree_class (forest, itree));
  /* Loop over all elements */
  for (t8locidx_t ielem = 0; ielem < num_elems; ++ielem){
    /* Get the element with tree-local-id ielem */
    const t8_element_t *elem = t8_forest_get_element_in_tree (forest, itree, ielem);
    /* Get the level of the element */
    elem_level = scheme->t8_element_level (tree_class, elem);
  }
}

How do we achieve that (without a memory overhead)?

An option would be to equip each element with a pointer to the forests scheme and their local tree id, so that they can relay the element functions to the scheme. But this would imply another pointer and t8_locidx_t inside an element. This is not an option.
But since an element iterator would basically loop over all trees and all elements in that tree, it has to keep track of the local tree and element ids. Furthermore, the element iterator would be provided by the forest. So it can also contain a pointer to the forest or its scheme. This way the iterator keeps track off everything and relays the function calls to the scheme and the only memory overhead would be one pointer in the iterator, which exists only once per process.