On 16 December 2017 at 13:12, René Scharfe <l.s.r@xxxxxx> wrote:
> prepare_revision_walk() allows callers to take ownership of the array of
> pending objects by setting the rev_info flag "leak_pending" and copying
> the object_array "pending". They use it to clear commit marks after
> setup is done. This interface is brittle enough that it requires
> extensive comments.
>
> Provide an easier way by adding a function that can hand over the array
> to a caller-supplied output parameter and converting all users of the
> flag "leak_pending" to call prepare_revision_walk_extended() instead.
>
> Signed-off-by: Rene Scharfe <l.s.r@xxxxxx>
> ---
> Documentation/technical/api-revision-walking.txt | 6 ++++++
> bisect.c | 17 +++++------------
> builtin/checkout.c | 9 +--------
> bundle.c | 9 +--------
> revision.c | 10 +++++++++-
> revision.h | 14 ++------------
> 6 files changed, 24 insertions(+), 41 deletions(-)
>
> diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt
> index 55b878ade8..9dc573d2ec 100644
> --- a/Documentation/technical/api-revision-walking.txt
> +++ b/Documentation/technical/api-revision-walking.txt
> @@ -50,6 +50,12 @@ function.
> returns any error (non-zero return code) and if it does not, you can
> start using get_revision() to do the iteration.
>
> +`prepare_revision_walk_extended`::
> +
> + Like prepare_revision_walk(), but allows callers to take ownership
> + of the array of pending objects by passing an object_array pointer
> + as the second parameter; passing NULL clears the array.
This might make someone wonder what the difference between passing NULL
and using `prepare_revision_walk()` is. Perhaps: "passing NULL clears
the array, just as prepare_revision_walk() would." Possibly only matters
once we gain more parameters, and maybe not even then...
The name of your new function ("..._extended") doesn't describe the
nature of the extended behavior and made me wonder if it was too
generic. But that genericness might be a good thing. When/If we need to
tweak the behavior along some other axis, we can add a third parameter
to ..._extended and pass NULL/0 as appropriate. The simple cases will
stay simple and we won't gain lots of functions with minor differences.
> diff --git a/builtin/checkout.c b/builtin/checkout.c
> index e1e157d205..1f04f5d5e5 100644
> --- a/builtin/checkout.c
> +++ b/builtin/checkout.c
> @@ -796,14 +796,7 @@ static void orphaned_commit_warning(struct commit *old, struct commit *new)
> add_pending_oid(&revs, "HEAD", &new->object.oid, UNINTERESTING);
>
> /* Save pending objects, so they can be cleaned up later. */
> - refs = revs.pending;
> - revs.leak_pending = 1;
> -
> - /*
> - * prepare_revision_walk (together with .leak_pending = 1) makes us
> - * the sole owner of the list of pending objects.
> - */
> - if (prepare_revision_walk(&revs))
> + if (prepare_revision_walk_extended(&revs, &refs))
> die(_("internal error in revision walk"));
> if (!(old->object.flags & UNINTERESTING))
> suggest_reattach(old, &revs);
> diff --git a/bundle.c b/bundle.c
> index 93290962c9..6af6e38c40 100644
> --- a/bundle.c
> +++ b/bundle.c
> @@ -158,14 +158,7 @@ int verify_bundle(struct bundle_header *header, int verbose)
> setup_revisions(2, argv, &revs, NULL);
>
> /* Save pending objects, so they can be cleaned up later. */
> - refs = revs.pending;
> - revs.leak_pending = 1;
> -
> - /*
> - * prepare_revision_walk (together with .leak_pending = 1) makes us
> - * the sole owner of the list of pending objects.
> - */
> - if (prepare_revision_walk(&revs))
> + if (prepare_revision_walk_extended(&revs, &refs))
> die(_("revision walk setup failed"));
>
> i = req_nr;
This copy-paste coding that you get rid of here can be attributed to me.
I obviously like your cleaned-up version much better.
> diff --git a/revision.h b/revision.h
> index 54761200ad..5d4b475334 100644
> --- a/revision.h
> +++ b/revision.h
> @@ -150,18 +150,6 @@ struct rev_info {
> date_mode_explicit:1,
> preserve_subject:1;
> unsigned int disable_stdin:1;
> - /*
> - * Set `leak_pending` to prevent `prepare_revision_walk()` from clearing
> - * the array of pending objects (`pending`). It will still forget about
> - * the array and its entries, so they really are leaked. This can be
> - * useful if the `struct object_array` `pending` is copied before
> - * calling `prepare_revision_walk()`. By setting `leak_pending`, you
> - * effectively claim ownership of the old array, so you should most
> - * likely call `object_array_clear(&pending_copy)` once you are done.
> - * Observe that this is about ownership of the array and its entries,
> - * not the commits referenced by those entries.
> - */
> - unsigned int leak_pending:1;
> /* --show-linear-break */
> unsigned int track_linear:1,
> track_first_time:1,
The commit message doesn't mention that you drop `leak_pending`, but
maybe that's obvious enough since you convert all users.
Thanks for tidying up,
Martin
