Should reset_revision_walk clear more flags?

Should reset_revision_walk clear more flags?

[Mike Hommey]

Hi,

While trying to use the revision walking API twice in a row, I noticed
that the second time for the same setup would not yield the same result.
In my case, it turns out I was requesting boundaries, and
reset_revision_walk() is not resetting CHILD_SHOWN and BOUNDARY, both
required to be reset for the second revision walk to work.

So the question is, are consumers supposed to reset those flags on their
own, or should reset_revision_walk clear them?

Mike

Re: Should reset_revision_walk clear more flags?

[Mike Hommey]

On Mon, Dec 05, 2016 at 08:09:58AM +0900, Mike Hommey wrote:
> Hi,
> 
> While trying to use the revision walking API twice in a row, I noticed
> that the second time for the same setup would not yield the same result.
> In my case, it turns out I was requesting boundaries, and
> reset_revision_walk() is not resetting CHILD_SHOWN and BOUNDARY, both
> required to be reset for the second revision walk to work.

and TREESAME when using different pathspecs.

Mike

Re: Should reset_revision_walk clear more flags?

[Jeff King]

On Mon, Dec 05, 2016 at 08:09:58AM +0900, Mike Hommey wrote:

> While trying to use the revision walking API twice in a row, I noticed
> that the second time for the same setup would not yield the same result.
> In my case, it turns out I was requesting boundaries, and
> reset_revision_walk() is not resetting CHILD_SHOWN and BOUNDARY, both
> required to be reset for the second revision walk to work.
> 
> So the question is, are consumers supposed to reset those flags on their
> own, or should reset_revision_walk clear them?

I would think that reset_revision_walk() should reset any flags set by
the revision-walking code (so anything set by calling init_revisions(),
and then either a call into list_objects() or repeated calls of
get_revision()).

Which I think would include both of the flags you mentioned, along with
others like SYMMETRIC_LEFT, PATCHSAME, etc. Probably really everything
mentioned in revision.h, which should be summed up as ALL_REV_FLAGS.
Some callsites already seem to feed that to clear_commit_marks().

I doubt you can go too wrong by clearing more flags. It's possible that
some caller is relying on a flag _not_ being cleared between two
traversals, but in that case it should probably be using
clear_commit_marks() or clear_object_flags() explicitly to make it clear
what it expects to be saved.

-Peff

Re: Should reset_revision_walk clear more flags?

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> Which I think would include both of the flags you mentioned, along with
> others like SYMMETRIC_LEFT, PATCHSAME, etc. Probably really everything
> mentioned in revision.h, which should be summed up as ALL_REV_FLAGS.
> Some callsites already seem to feed that to clear_commit_marks().
>
> I doubt you can go too wrong by clearing more flags. 

This and ...

> It's possible that
> some caller is relying on a flag _not_ being cleared between two
> traversals, but in that case it should probably be using
> clear_commit_marks() or clear_object_flags() explicitly to make it clear
> what it expects to be saved.

... this are contradictory, no?  

A caller may use two sets of its own flags in addition to letting
the traversal machinery use the basic ones, and it may want to keep
one of its own two sets while clearing the other set.  It would
clear_commit_marks() to clear the latter.  And then it would let
that the next traversal to reset_revision_walk() clear the basic
ones.

So if you make reset_revision_walk() clear "more flags", that would
break such a caller that is using clear_commit_marks() to make it
clear what its expectations are, no?

I dunno.

Re: Should reset_revision_walk clear more flags?

[Jeff King]

On Sun, Dec 04, 2016 at 11:26:04PM -0800, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> > Which I think would include both of the flags you mentioned, along with
> > others like SYMMETRIC_LEFT, PATCHSAME, etc. Probably really everything
> > mentioned in revision.h, which should be summed up as ALL_REV_FLAGS.
> > Some callsites already seem to feed that to clear_commit_marks().
> >
> > I doubt you can go too wrong by clearing more flags. 
> 
> This and ...
> 
> > It's possible that
> > some caller is relying on a flag _not_ being cleared between two
> > traversals, but in that case it should probably be using
> > clear_commit_marks() or clear_object_flags() explicitly to make it clear
> > what it expects to be saved.
> 
> ... this are contradictory, no?

I don't think so. If you are calling reset_revision_walk(), then I'm not
sure you have any right to expect that particular flags are left intact.
You _should_ be using an option that lets you specify the full set of
flags, rather than making an implicit assumption about which flags are
left.

In other words, I'd much rather see:

  clear_object_flags(ALL_REV_FLAGS & (~TMP_MARK));

than:

  /* This leaves TMP_MARK intact! */
  reset_revision_walk();

if you need to leave TMP_MARK intact.

Which isn't to say every caller does it correctly already. My claim
above is only "should", not "does". :)

But given that many of them _do_ use the more specific flag-clearing
functions, I think most of the calls to reset_revision_walk() are
blanket "I'm done now, clean up after me" calls.

> A caller may use two sets of its own flags in addition to letting
> the traversal machinery use the basic ones, and it may want to keep
> one of its own two sets while clearing the other set.  It would
> clear_commit_marks() to clear the latter.  And then it would let
> that the next traversal to reset_revision_walk() clear the basic
> ones.
> 
> So if you make reset_revision_walk() clear "more flags", that would
> break such a caller that is using clear_commit_marks() to make it
> clear what its expectations are, no?

I'd argue that it should not be calling reset_revision_walk() at all if
it wants anything saved. It should mask out the flags it wants, as
above. But I do realize that reasoning is circular: it's OK for
reset_revision_walk() to reset everything because that's what it does,
or at least should do from its name. :)

-Peff