Touch-up counsel-outline

[basil-conto]

Re: #1681, #1684
Cc: @ericdanan

Please review each commit in turn, I have tried to document and justify each relatively atomic change.

Questions

Should we be worried about all the markers accumulated by counsel-outline-candidates? Should we try to "free" them post-completion? Quoth (elisp) Overview of Markers:

   Insertion and deletion in a buffer must check all the markers and
relocate them if necessary.  This slows processing in a buffer with a
large number of markers.  For this reason, it is a good idea to make a
marker point nowhere if you are sure you don’t need it any more.
Markers that can no longer be accessed are eventually removed (see
Garbage Collection).

[abo-abo]

The same expression is called twice. Typo?

[basil-conto]

Oops, thanks. It's an artefact of trying to split the doc and code changes into separate commits, which is fixed by the subsequent doc fix. I'll clean up the commits now.

[abo-abo]

Thanks a lot. Looks good to me, except the suspected typo that I mentioned a minute earlier.

Should we be worried about all the markers accumulated by counsel-outline-candidates?

If the worries are backed up by some basic profiling, we should. But if the cost is negligible, we can ignore it.

Should we try to "free" them post-completion?

If it doesn't complicate the code too much.

[basil-conto]

Looks good to me, except the suspected typo that I mentioned a minute earlier.

Thanks, the commits should be fixed now.

Should we be worried about all the markers accumulated by counsel-outline-candidates?

If the worries are backed up by some basic profiling, we should. But if the cost is negligible, we can ignore it.

Should we try to "free" them post-completion?

If it doesn't complicate the code too much.

I'll leave this investigation for a future time, if no-one else comments / steps up.

[basil-conto]

I'll leave this investigation for a future time, if no-one else comments / steps up.

The future is now! (Is it obvious I'm procrastinating doing other work? :)

I've added a commit which frees any markers returned by counsel-outline-candidates.

I didn't notice or profile a performance hit before this commit, but what I did notice is that, after the first call to counsel-outline within an org-mode buffer, the buffer contained hundreds more positions with markers pointing to them (a ~7x increase). I did this by counting buffer-has-markers-at hits.

I'd rather err on the side of caution and simply free these markers after their use, given how simple it seems to do so (is it kosher to free them after the call to ivy-read?).

[abo-abo]

Thanks.

is it kosher to free them after the call to ivy-read

If you want to be very precise, :unwind can be used (see e.g. swiper--ivy). That way, even if the user C-g, the resources will be cleaned up.

[basil-conto]

If you want to be very precise, :unwind can be used (see e.g. swiper--ivy). That way, even if the user C-g, the resources will be cleaned up.

Doesn't :unwind get called too early (it's called before ivy-call)?

[abo-abo]

You're right, I didn't consider that.

[ericdanan]

Sorry to reply late.

Freeing the markers has the drawback that ivy-resume no longer works after counsel-outline. If storing a marker for each candidate is too costly, an alternative could be to instead store the buffer name and value of point in the candidate, although I understand this would be less robust.

[basil-conto]

Good point, thanks @ericdanan. I've reverted the marker freeing commit in #1717; sorry about that.

[basil-conto]

If storing a marker for each candidate is too costly, an alternative could be to instead store the buffer name and value of point in the candidate, although I understand this would be less robust.

It would definitely be less robust, but is ivy-resume ever realistically used after significant changes have been made to the source of the collection? More importantly, does anyone really expect it to work robustly in such cases?

[abo-abo]

It would definitely be less robust, but is ivy-resume ever realistically used after significant changes have been made to the source of the collection?

We could try to make it more robust, similar to how g will re-update an ivy-occur buffer. But that would probably require the collection argument to be a function so that we would call it once more.