@matheusbsbs / matheus-bagliano / commits / 82c39c6055

refs/iterator: provide infrastructure to re-seek iterators

Reftable iterators need to be scrapped after they have either been exhausted or aren't useful to the caller anymore, and it is explicitly not possible to reuse them for iterations. But enabling for reuse of iterators may allow us to tune them by reusing internal state of an iterator. The reftable iterators for example can already be reused internally, but we're not able to expose this to any users outside of the reftable backend. Introduce a new `.seek` function in the ref iterator vtable that allows callers to seek an iterator multiple times. It is expected to be functionally the same as calling `refs_ref_iterator_begin()` with a different (or the same) prefix. Note that it is not possible to adjust parameters other than the seeked prefix for now, so exclude patterns, trimmed prefixes and flags will remain unchanged. We do not have a usecase for changing these parameters right now, but if we ever find one we can adapt accordingly. Implement the callback for trivial cases. The other iterators will be implemented in subsequent commits. Signed-off-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Patrick Steinhardt committed Mar 12, 2025 at 16:56 UTC 82c39c6055b5340f0e50acbe01a97e51d3907fec

3 files changed +59

refs/debug.c

+11

@@ -169,6 +169,16 @@ static int debug_ref_iterator_advance(struct ref_iterator *ref_iterator)

169 return res;

170 }

171

172 +static int debug_ref_iterator_seek(struct ref_iterator *ref_iterator,

173 + const char *prefix)

174 +{

175 + struct debug_ref_iterator *diter =

176 + (struct debug_ref_iterator *)ref_iterator;

177 + int res = diter->iter->vtable->seek(diter->iter, prefix);

178 + trace_printf_key(&trace_refs, "iterator_seek: %s: %d\n", prefix ? prefix : "", res);

179 + return res;

180 +}

181 +

182 static int debug_ref_iterator_peel(struct ref_iterator *ref_iterator,

183 struct object_id *peeled)

184 {

@@ -189,6 +199,7 @@ static void debug_ref_iterator_release(struct ref_iterator *ref_iterator)

199

200 static struct ref_iterator_vtable debug_ref_iterator_vtable = {

201 .advance = debug_ref_iterator_advance,

202 + .seek = debug_ref_iterator_seek,

203 .peel = debug_ref_iterator_peel,

204 .release = debug_ref_iterator_release,

205 };

refs/iterator.c

+24

@@ -15,6 +15,12 @@ int ref_iterator_advance(struct ref_iterator *ref_iterator)

15 return ref_iterator->vtable->advance(ref_iterator);

16 }

18 +int ref_iterator_seek(struct ref_iterator *ref_iterator,

19 + const char *prefix)

20 +{

21 + return ref_iterator->vtable->seek(ref_iterator, prefix);

22 +}

23 +

24 int ref_iterator_peel(struct ref_iterator *ref_iterator,

25 struct object_id *peeled)

26 {

@@ -50,6 +56,12 @@ static int empty_ref_iterator_advance(struct ref_iterator *ref_iterator UNUSED)

56 return ITER_DONE;

57 }

59 +static int empty_ref_iterator_seek(struct ref_iterator *ref_iterator UNUSED,

60 + const char *prefix UNUSED)

61 +{

62 + return 0;

63 +}

64 +

65 static int empty_ref_iterator_peel(struct ref_iterator *ref_iterator UNUSED,

66 struct object_id *peeled UNUSED)

67 {

@@ -62,6 +74,7 @@ static void empty_ref_iterator_release(struct ref_iterator *ref_iterator UNUSED)

75 static struct ref_iterator_vtable empty_ref_iterator_vtable = {

76 .advance = empty_ref_iterator_advance,

77 + .seek = empty_ref_iterator_seek,

78 .peel = empty_ref_iterator_peel,

79 .release = empty_ref_iterator_release,

80 };

@@ -373,6 +386,16 @@ static int prefix_ref_iterator_advance(struct ref_iterator *ref_iterator)

386 return ok;

387 }

388

389 +static int prefix_ref_iterator_seek(struct ref_iterator *ref_iterator,

390 + const char *prefix)

391 +{

392 + struct prefix_ref_iterator *iter =

393 + (struct prefix_ref_iterator *)ref_iterator;

394 + free(iter->prefix);

395 + iter->prefix = xstrdup_or_null(prefix);

396 + return ref_iterator_seek(iter->iter0, prefix);

397 +}

398 +

399 static int prefix_ref_iterator_peel(struct ref_iterator *ref_iterator,

400 struct object_id *peeled)

401 {

@@ -392,6 +415,7 @@ static void prefix_ref_iterator_release(struct ref_iterator *ref_iterator)

415

416 static struct ref_iterator_vtable prefix_ref_iterator_vtable = {

417 .advance = prefix_ref_iterator_advance,

418 + .seek = prefix_ref_iterator_seek,

419 .peel = prefix_ref_iterator_peel,

420 .release = prefix_ref_iterator_release,

421 };

refs/refs-internal.h

+24

@@ -327,6 +327,22 @@ struct ref_iterator {

327 */

328 int ref_iterator_advance(struct ref_iterator *ref_iterator);

329

330 +/*

331 + * Seek the iterator to the first reference with the given prefix.

332 + * The prefix is matched as a literal string, without regard for path

333 + * separators. If prefix is NULL or the empty string, seek the iterator to the

334 + * first reference again.

335 + *

336 + * This function is expected to behave as if a new ref iterator with the same

337 + * prefix had been created, but allows reuse of iterators and thus may allow

338 + * the backend to optimize. Parameters other than the prefix that have been

339 + * passed when creating the iterator will remain unchanged.

340 + *

341 + * Returns 0 on success, a negative error code otherwise.

342 + */

343 +int ref_iterator_seek(struct ref_iterator *ref_iterator,

344 + const char *prefix);

345 +

346 /*

347 * If possible, peel the reference currently being viewed by the

348 * iterator. Return 0 on success.

@@ -445,6 +461,13 @@ void base_ref_iterator_init(struct ref_iterator *iter,

461 */

462 typedef int ref_iterator_advance_fn(struct ref_iterator *ref_iterator);

463

464 +/*

465 + * Seek the iterator to the first reference matching the given prefix. Should

466 + * behave the same as if a new iterator was created with the same prefix.

467 + */

468 +typedef int ref_iterator_seek_fn(struct ref_iterator *ref_iterator,

469 + const char *prefix);

470 +

471 /*

472 * Peels the current ref, returning 0 for success or -1 for failure.

473 */

@@ -459,6 +482,7 @@ typedef void ref_iterator_release_fn(struct ref_iterator *ref_iterator);

482

483 struct ref_iterator_vtable {

484 ref_iterator_advance_fn *advance;

485 + ref_iterator_seek_fn *seek;

486 ref_iterator_peel_fn *peel;

487 ref_iterator_release_fn *release;

488 };