mirror of
https://github.com/git/git.git
synced 2025-12-05 18:47:16 -06:00
cec2b6f55a
The ref and reflog iterators have their lifecycle attached to iteration:
once the iterator reaches its end, it is automatically released and the
caller doesn't have to care about that anymore. When the iterator should
be released before it has been exhausted, callers must explicitly abort
the iterator via `ref_iterator_abort()`.
This lifecycle is somewhat unusual in the Git codebase and creates two
problems:
- Callsites need to be very careful about when exactly they call
`ref_iterator_abort()`, as calling the function is only valid when
the iterator itself still is. This leads to somewhat awkward calling
patterns in some situations.
- It is impossible to reuse iterators and re-seek them to a different
prefix. This feature isn't supported by any iterator implementation
except for the reftable iterators anyway, but if it was implemented
it would allow us to optimize cases where we need to search for
specific references repeatedly by reusing internal state.
Detangle the lifecycle from iteration so that we don't deallocate the
iterator anymore once it is exhausted. Instead, callers are now expected
to always call a newly introduce `ref_iterator_free()` function that
deallocates the iterator and its internal state.
Note that the `dir_iterator` is somewhat special because it does not
implement the `ref_iterator` interface, but is only used to implement
other iterators. Consequently, we have to provide `dir_iterator_free()`
instead of `dir_iterator_release()` as the allocated structure itself is
managed by the `dir_iterator` interfaces, as well, and not freed by
`ref_iterator_free()` like in all the other cases.
While at it, drop the return value of `ref_iterator_abort()`, which
wasn't really required by any of the iterator implementations anyway.
Furthermore, stop calling `base_ref_iterator_free()` in any of the
backends, but instead call it in `ref_iterator_free()`.
Signed-off-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
82 lines
2.1 KiB
C
82 lines
2.1 KiB
C
#ifndef ITERATOR_H
|
|
#define ITERATOR_H
|
|
|
|
/*
|
|
* Generic constants related to iterators.
|
|
*/
|
|
|
|
/*
|
|
* The attempt to advance the iterator was successful; the iterator
|
|
* reflects the new current entry.
|
|
*/
|
|
#define ITER_OK 0
|
|
|
|
/*
|
|
* The iterator is exhausted.
|
|
*/
|
|
#define ITER_DONE -1
|
|
|
|
/*
|
|
* The iterator experienced an error. The iteration has been aborted
|
|
* and the iterator has been freed.
|
|
*/
|
|
#define ITER_ERROR -2
|
|
|
|
/*
|
|
* Return values for selector functions for merge iterators. The
|
|
* numerical values of these constants are important and must be
|
|
* compatible with ITER_DONE and ITER_ERROR.
|
|
*/
|
|
enum iterator_selection {
|
|
/* End the iteration without an error: */
|
|
ITER_SELECT_DONE = ITER_DONE,
|
|
|
|
/* Report an error and abort the iteration: */
|
|
ITER_SELECT_ERROR = ITER_ERROR,
|
|
|
|
/*
|
|
* The next group of constants are masks that are useful
|
|
* mainly internally.
|
|
*/
|
|
|
|
/* The LSB selects whether iter0/iter1 is the "current" iterator: */
|
|
ITER_CURRENT_SELECTION_MASK = 0x01,
|
|
|
|
/* iter0 is the "current" iterator this round: */
|
|
ITER_CURRENT_SELECTION_0 = 0x00,
|
|
|
|
/* iter1 is the "current" iterator this round: */
|
|
ITER_CURRENT_SELECTION_1 = 0x01,
|
|
|
|
/* Yield the value from the current iterator? */
|
|
ITER_YIELD_CURRENT = 0x02,
|
|
|
|
/* Discard the value from the secondary iterator? */
|
|
ITER_SKIP_SECONDARY = 0x04,
|
|
|
|
/*
|
|
* The constants that a selector function should usually
|
|
* return.
|
|
*/
|
|
|
|
/* Yield the value from iter0: */
|
|
ITER_SELECT_0 = ITER_CURRENT_SELECTION_0 | ITER_YIELD_CURRENT,
|
|
|
|
/* Yield the value from iter0 and discard the one from iter1: */
|
|
ITER_SELECT_0_SKIP_1 = ITER_SELECT_0 | ITER_SKIP_SECONDARY,
|
|
|
|
/* Discard the value from iter0 without yielding anything this round: */
|
|
ITER_SKIP_0 = ITER_CURRENT_SELECTION_1 | ITER_SKIP_SECONDARY,
|
|
|
|
/* Yield the value from iter1: */
|
|
ITER_SELECT_1 = ITER_CURRENT_SELECTION_1 | ITER_YIELD_CURRENT,
|
|
|
|
/* Yield the value from iter1 and discard the one from iter0: */
|
|
ITER_SELECT_1_SKIP_0 = ITER_SELECT_1 | ITER_SKIP_SECONDARY,
|
|
|
|
/* Discard the value from iter1 without yielding anything this round: */
|
|
ITER_SKIP_1 = ITER_CURRENT_SELECTION_0 | ITER_SKIP_SECONDARY
|
|
};
|
|
|
|
#endif /* ITERATOR_H */
|