Cursors that iterate over non-empty trails

[tuulos]

Problem

The current API requires that you set the cursor explicitly for each trail using tdb_get_trail. When combined with event filters, it is possible that some trails yield no events. Hence, even empty trails require at least two function calls, tdb_get_trail(); tdb_cursor_next(). For language bindings that have a high function call overhead, e.g. CGo and Python, the cost of redundant function calls can be high.

Proposed Solutions

The problem with redundant function calls could be solved as follows:

1. If it is desirable to know exactly which trails are iterated over, we could introduce

   uint64_t tdb_get_next_trail(tdb_cursor *cursor)
   

   which resets the cursor to the next non-empty trail and returns the trail_id. To iterate over all non-empty trails, use while((trail_id = tdb_get_next_trail(cursor))). Especially for highly selective filters, this is much more efficient than calling tdb_get_trail(); tdb_cursor_next() for every trail.

2. If it is desirable to iterate over all events, e.g. to collect TrailDB-wide statistics, we could introduce

   const tdb_event *tdb_cursor_next_all(tdb_cursor *cursor, uint64_t *trail_id)
   

   To iterate overall all events, use while ((event = tdb_cursor_next_all(cursor, &trail_id)).