Use cases for post-redisplay hooks

Use cases for post-redisplay hooks

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 1434 bytes --]

Hi emacs-devel,

As a prelude to implementing the actual functionality, I'd like to get a clearer picture of what use cases exist for post-redisplay hooks.

Here are the ones that I'm currently aware of; can you think of other ones?

1. (my own) Generating emacs screenshots. You can see a demo at http://web.mit.edu/cpitcla/www/emacs-screencast-annot.gif (let me know what you think!). Other hooks do not work because:
  - pre-redisplay-functions are called too early
  - pre- and post-command-hook do not run often enough (in the screencast above, see the butterfly animation, for example)
  - window-related hooks do not run often enough either
  - redisplay-end-trigger-functions are tricky to use, and deprecated

2. (Keith David Bershatsky + Michael Heerdegen @ https://lists.gnu.org/archive/html/bug-gnu-emacs/2016-01/msg01013.html) Updating overlays after scrolling.  The bug thread is pretty long and subtle, but this issue has also been discussed on emacs.stackexchanged IIRC.

3. (Stefan? @ https://lists.gnu.org/archive/html/emacs-devel/2009-02/msg00785.html) Running code every time "something visible" happens (e.g. due to process filters)

For number 1, and potentially number 3, a hook that run after redisplay completes entirely would work. For number 2, things are less clear. Michael, Keith, and Eli, do you have ideas of when in the display cycle such a hook should run?

Thanks!
Clément.



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: Use cases for post-redisplay hooks

[Eli Zaretskii]

> From: Clément Pit--Claudel <clement.pit@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Monnier <monnier@iro.umontreal.ca>,
>  michael_heerdegen@web.de, esq@lawlist.com
> Date: Mon, 4 Jul 2016 12:39:50 -0400
> 
> 2. (Keith David Bershatsky + Michael Heerdegen @ https://lists.gnu.org/archive/html/bug-gnu-emacs/2016-01/msg01013.html) Updating overlays after scrolling.  The bug thread is pretty long and subtle, but this issue has also been discussed on emacs.stackexchanged IIRC.

AFAIU, this one is not a candidate for post-redisplay hook.  Scrolling
doesn't happen every redisplay, only some of them; and we already have
a hook for that.

Re: Use cases for post-redisplay hooks

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 1520 bytes --]

On 2016-07-04 13:02, Eli Zaretskii wrote:
>> From: Clément Pit--Claudel <clement.pit@gmail.com>
>> Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Monnier <monnier@iro.umontreal.ca>,
>>  michael_heerdegen@web.de, esq@lawlist.com
>> Date: Mon, 4 Jul 2016 12:39:50 -0400
>>
>> 2. (Keith David Bershatsky + Michael Heerdegen @ https://lists.gnu.org/archive/html/bug-gnu-emacs/2016-01/msg01013.html) Updating overlays after scrolling.  The bug thread is pretty long and subtle, but this issue has also been discussed on emacs.stackexchanged IIRC.
> 
> AFAIU, this one is not a candidate for post-redisplay hook.  Scrolling
> doesn't happen every redisplay, only some of them; and we already have
> a hook for that.

Ok. I got mislead by this message:

     From: 	Eli Zaretskii
     Subject: 	bug#22404: 25.1.50; Forcing `window-scroll-functions` to run.
     Date: 	Fri, 29 Jan 2016 16:37:16 +0200

     > From: Michael Heerdegen <address@hidden>
     > Cc: Keith David Bershatsky <address@hidden>,  address@hidden
     > Date: Fri, 29 Jan 2016 13:00:42 +0100
     >
     > Anyway, using pre-command-hook is too late for us: it's not executed
     > unless the next input arrives, so you have to hit a key until
     > decorations or whatever get updated.

     Then maybe we need a post-redisplay-hook.

But in that case, it seems that the only two currently identified use cases would be happy with a hook running after redisplay has completed in full. Let's see whether other examples pop up :)


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: Use cases for post-redisplay hooks

[Keith David Bershatsky]

I am using a slightly modified version of Emacs that has what I call a `window-start-end-hook`, which lets me draw overlays on just the visible window every command loop.  I needs more work, but that is the general idea of the modification.

There are certain movements of point that are not covered by the `window-scroll-functions` hook, so that hook cannot be used reliably for the above-mentioned purpose.  And, the hook *may* run more than once each command loop, leading to potentially wasted time spent running an overlay function that will need to run again anyway before the display cycle finishes.

The main concern I had regarding a `post-redisplay-hook` would be that users would add Lisp code to the hook that alters `window-start` and `window-end`, and I felt that an additional check was needed before redisplay finishes to make sure that things are where they should be -- e.g., the cursor location.  The key ingredient (for me, at least) would be that the `post-redisplay-hook` should provide guaranteed correct values for `window-start` and `window-end`.

Thanks,

Keith

Re: Use cases for post-redisplay hooks

[Stefan Monnier]

> 3. (Stefan? @
> https://lists.gnu.org/archive/html/emacs-devel/2009-02/msg00785.html)
> Running code every time "something visible" happens (e.g. due to process
> filters)

FWIW, I don't know what this "use case" was referring to, really.
I tried to re-read the thread, but still haven't found the answer.
I think I just wrote "per/post-redisplay-hook" there because I had a use
for a pre-redisplay-hook (which I finally satisfied years later with
pre-redisplay-function) and figured that it would naturally come as
a pair.


        Stefan

Re: Use cases for post-redisplay hooks

[Stefan Monnier]

> I am using a slightly modified version of Emacs that has what
> I call a `window-start-end-hook`, which lets me draw overlays on just the
> visible window every command loop.  I needs more work, but that is the
> general idea of the modification.

Could you clarify what you use it for?

Also is it run after redisplay?  If so, how does it work?  I mean how do
you add overlays *after* redisplay?  Do you trigger a second redisplay
right after the first, or is it simply that your overlays don't affect
the display?

> There are certain movements of point that are not covered by the
> `window-scroll-functions` hook, so that hook cannot be used reliably for the
> above-mentioned purpose.

Not sure what point has to do with window-start-end-hook.

> And, the hook *may* run more than once each command loop, leading to
> potentially wasted time spent running an overlay function that will
> need to run again anyway before the display cycle finishes.

Is that a problem in practice?


        Stefan

Re: Use cases for post-redisplay hooks

[Keith David Bershatsky]

[-- Attachment #1: Type: text/plain, Size: 3633 bytes --]

The implementation of the `window-start-end-hook` is probably easier to explain with a diff, which is attached.  I haven't worked much on the hook since March 11, 2016, so it applies to the master branch on or about that date.  [I think I made a few very minor changes after that, but don't have a diff ready at this time.]

Each command loop, I place the following overlays on just the visible window:

* [Maybe] draw a vertical line that tracks the cursor position, which is compatible with `word-wrap` enabled.  Sometimes I force it to draw immediately, but most of the time it is on an idle timer.  The line stretches from the top of the window to the bottom of the window.

* Place line numbers to the left of the left-fringe.

* Place pilcrows at the end of each line.  [The `buffer-display-table` can't be used for this because those pilcrows are not compatible with the vertical line, which also adds pilcrows.]

* Draw a horizontal line underneath where the cursor is located.  The line stretches from the left-fringe to the right-fringe, and sometimes some I add bitmaps in the fringe.

* If there is a region active, then the region is colored appropriately to work with the cross-hairs (describe-above).

* I also run some other stuff at the tail end, which is not really that important to the use case -- e.g., parentheses highlighting, and flyspell.

The reason I mentioned the `window-scroll-functions` hook was an assumption (on my part) that Clément had initially categorized my potential usage of the proposed `post-redisplay-hook` as only relating to scrolling.  I just wanted to clarify / differentiate my proposed use case as needing `window-start` and `window-end` each command loop.

With respect to the hook running more than once each command loop, it is only a problem for me because my calculations are costly time-wise (e.g., `vertical-motion').  So, I only want to do it one time each command loop.  The `window-start-end-hook` only fires completely when point is fully visible and when the values for `window-start` and `window-end` are correct (at least in so far as my testing has shown).  Someone who uses a simple function attached to a hook that runs multiple times each command loop would not likely be bothered if there is a little waste.  I suffer from a little O.C.D., so just the thought of a function running for no reason at all bothers me.  :)

Keith

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

At Mon, 04 Jul 2016 18:06:33 -0400,
Stefan Monnier wrote:
> 
> > I am using a slightly modified version of Emacs that has what
> > I call a `window-start-end-hook`, which lets me draw overlays on just the
> > visible window every command loop.  I needs more work, but that is the
> > general idea of the modification.
> 
> Could you clarify what you use it for?
> 
> Also is it run after redisplay?  If so, how does it work?  I mean how do
> you add overlays *after* redisplay?  Do you trigger a second redisplay
> right after the first, or is it simply that your overlays don't affect
> the display?
> 
> > There are certain movements of point that are not covered by the
> > `window-scroll-functions` hook, so that hook cannot be used reliably for the
> > above-mentioned purpose.
> 
> Not sure what point has to do with window-start-end-hook.
> 
> > And, the hook *may* run more than once each command loop, leading to
> > potentially wasted time spent running an overlay function that will
> > need to run again anyway before the display cycle finishes.
> 
> Is that a problem in practice?
> 
> 
>         Stefan


[-- Attachment #2: window_start_end_hook.diff --]
[-- Type: application/diff, Size: 15202 bytes --]

Re: Use cases for post-redisplay hooks

[Eli Zaretskii]

> Date:  Mon, 04 Jul 2016 14:42:46 -0700
> From:  Keith David Bershatsky <esq@lawlist.com>
> Cc:  emacs-devel@gnu.org,Eli Zaretskii <eliz@gnu.org>,Stefan Monnier <monnier@iro.umontreal.ca>,michael_heerdegen@web.de
> 
> The main concern I had regarding a `post-redisplay-hook` would be that users would add Lisp code to the hook that alters `window-start` and `window-end`

We could check that and prevent this, if we so decide.

Re: Use cases for post-redisplay hooks

[Stefan Monnier]

> The implementation of the `window-start-end-hook` is probably easier to
> explain with a diff, which is attached.

Hmm... my understanding of the redisplay code is sufficiently fuzzy that
your patch doesn't actually tell me how it's supposed to work.
More specifically the timing is unclear to me: the overlays you add from
your hook affect the display, so you need to run (the bulk of) the
redisplay code *after* running your hook.

So sounds more like a pre-redisplay-hook.  Except that you pre-compute
the expected window-end somehow.


        Stefan

Re: Use cases for post-redisplay hooks

[Keith David Bershatsky]

I can explain it in layman's terms, but I'm not familiar enough with how redisplay works to describe in computer language what happens exactly.  [I'm a hobbyist / tinkerer, but do not have any formal training in programming.]

I saw that the `window-scroll-functions` hook (hereinafter "WSF") returned correct values for `window-start` and `window-end` in some circumstances, but not all.  I saw that the WSF had about two (2) occasions where it is forced to run with a built-in flag, so I borrowed that functionality.  The `window-start-end-hook' (hereinafter "WSEH") is kind of like the WSF on steroids.  Wherever the WSF would normally be called, the WSEH is also called.  I added one (2) additional location for the WSEH to deal with mouse wheel scrolling.  I throw the switch on the WSEH every command loop.  The WSEH has a check to see if point is fully visible, because that is when `window-start` and `window-end` will not likely change again (so long as the Lisp function attached to the WSEH doesn't alter those value
 s in any way).  When point is fully visible, then the function attached to the WSEH runs and my overlays are placed on the visible window.

Keith

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

At Tue, 05 Jul 2016 04:12:30 -0400,
Stefan Monnier wrote:
> 
> > The implementation of the `window-start-end-hook` is probably easier to
> > explain with a diff, which is attached.
> 
> Hmm... my understanding of the redisplay code is sufficiently fuzzy that
> your patch doesn't actually tell me how it's supposed to work.
> More specifically the timing is unclear to me: the overlays you add from
> your hook affect the display, so you need to run (the bulk of) the
> redisplay code *after* running your hook.
> 
> So sounds more like a pre-redisplay-hook.  Except that you pre-compute
> the expected window-end somehow.
> 
> 
>         Stefan

Re: Use cases for post-redisplay hooks

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 1404 bytes --]

On 2016-07-04 18:50, Keith David Bershatsky wrote:
> The reason I mentioned the `window-scroll-functions` hook was an
> assumption (on my part) that Clément had initially categorized my
> potential usage of the proposed `post-redisplay-hook` as only
> relating to scrolling.  I just wanted to clarify / differentiate my
> proposed use case as needing `window-start` and `window-end` each
> command loop.

IIUC then the post-redisplay-hook thing wouldn't work very nicely: in general, it's going to run more often than once per command loop cycle.

> With respect to the hook running more than once each command loop, it
> is only a problem for me because my calculations are costly time-wise
> (e.g., `vertical-motion').  So, I only want to do it one time each
> command loop.

Would registering a post-command hook and incrementing a counter in there help? You would then predicate your costly calculations on the value of that counter having changed since the last time the calculations ran.

Even simpler: in a pre/post-command hook switch a `needs-recalculation' flag to t, and after completing the calculations (from whichever other hook you're using for them) switch `needs-recalculation' to nil. If the function doing the calculations is called when `needs-recalculation' is nil, then can exit immediately.

Or is there something more complex that I'm missing?

Clément.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: Use cases for post-redisplay hooks

[Keith David Bershatsky]

Yes, a `needs-recalculation` flag would be very useful -- i.e., when the values for `window-start` and `window-end` are correct and not going to change, then run the Lisp function (attached to the hook) that depends upon those values being correct.  A counter, however, may not be a reliable indicator of the above test.

[My assumption is that overlays could be placed before the screen visually refreshes, so that the overlays are visually present when redisplay finishes.]

Keith

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

At Thu, 7 Jul 2016 12:08:09 -0400,
Clément Pit--Claudel wrote:
> 
> On 2016-07-04 18:50, Keith David Bershatsky wrote:
> > The reason I mentioned the `window-scroll-functions` hook was an
> > assumption (on my part) that Clément had initially categorized my
> > potential usage of the proposed `post-redisplay-hook` as only
> > relating to scrolling.  I just wanted to clarify / differentiate my
> > proposed use case as needing `window-start` and `window-end` each
> > command loop.
> 
> IIUC then the post-redisplay-hook thing wouldn't work very nicely: in general, it's going to run more often than once per command loop cycle.
> 
> > With respect to the hook running more than once each command loop, it
> > is only a problem for me because my calculations are costly time-wise
> > (e.g., `vertical-motion').  So, I only want to do it one time each
> > command loop.
> 
> Would registering a post-command hook and incrementing a counter in there help? You would then predicate your costly calculations on the value of that counter having changed since the last time the calculations ran.
> 
> Even simpler: in a pre/post-command hook switch a `needs-recalculation' flag to t, and after completing the calculations (from whichever other hook you're using for them) switch `needs-recalculation' to nil. If the function doing the calculations is called when `needs-recalculation' is nil, then can exit immediately.
> 
> Or is there something more complex that I'm missing?
> 
> Clément.
> 
> [2 OpenPGP digital signature <application/pgp-signature (7bit)>]

Re: Use cases for post-redisplay hooks

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 2339 bytes --]

But I meant ­— can't you update this flag yourself, and do at most one recalculation per command loop?

On 2016-07-07 13:53, Keith David Bershatsky wrote:
> Yes, a `needs-recalculation` flag would be very useful -- i.e., when the values for `window-start` and `window-end` are correct and not going to change, then run the Lisp function (attached to the hook) that depends upon those values being correct.  A counter, however, may not be a reliable indicator of the above test.
> 
> [My assumption is that overlays could be placed before the screen visually refreshes, so that the overlays are visually present when redisplay finishes.]
> 
> Keith
> 
> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> 
> At Thu, 7 Jul 2016 12:08:09 -0400,
> Clément Pit--Claudel wrote:
>>
>> On 2016-07-04 18:50, Keith David Bershatsky wrote:
>>> The reason I mentioned the `window-scroll-functions` hook was an
>>> assumption (on my part) that Clément had initially categorized my
>>> potential usage of the proposed `post-redisplay-hook` as only
>>> relating to scrolling.  I just wanted to clarify / differentiate my
>>> proposed use case as needing `window-start` and `window-end` each
>>> command loop.
>>
>> IIUC then the post-redisplay-hook thing wouldn't work very nicely: in general, it's going to run more often than once per command loop cycle.
>>
>>> With respect to the hook running more than once each command loop, it
>>> is only a problem for me because my calculations are costly time-wise
>>> (e.g., `vertical-motion').  So, I only want to do it one time each
>>> command loop.
>>
>> Would registering a post-command hook and incrementing a counter in there help? You would then predicate your costly calculations on the value of that counter having changed since the last time the calculations ran.
>>
>> Even simpler: in a pre/post-command hook switch a `needs-recalculation' flag to t, and after completing the calculations (from whichever other hook you're using for them) switch `needs-recalculation' to nil. If the function doing the calculations is called when `needs-recalculation' is nil, then can exit immediately.
>>
>> Or is there something more complex that I'm missing?
>>
>> Clément.
>>
>> [2 OpenPGP digital signature <application/pgp-signature (7bit)>]
> 


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: Use cases for post-redisplay hooks

[Keith David Bershatsky]

With my limited computer skills, I was not able to find the "sweet spot" in the redisplay code where I knew for sure that `window-start' and `window-end' were always going to be correct such that I could easily set a hypothetical `needs-recalculation' flag to `nil'.  When I tried applying overlays too late in time in the redisplay cycle, there were visual problems updating the screen.

With my custom `window-start-end-hook' (with accepts a function with arguments for `window-start' and `window-end'), I use a test (built into the C code) to see whether point is fully visible before I run the Lisp function attached to the hook.  However, it assumes that `make-cursor-line-fully-visible' remains set at the default value of `t'.  I use `(setq scroll-conservatively 101)'.  On my todo-list, is to figure out how to incorporate a test (akin to `needs recalculation') for when `make-cursor-line-fully-visible' is set to `nil'.  Essentially, redisplay does less work when `make-cursor-line-fully-visible' is `nil'.  I've been using a custom build of Emacs with the `window-start-end-hook' since shortly after generating Emacs feature request 22404.

Keith

At Thu, 7 Jul 2016 15:44:13 -0400,
Clément Pit--Claudel wrote:
> 
> But I meant ­— can't you update this flag yourself, and do at most one recalculation per command loop?

Re: Use cases for post-redisplay hooks

[Clément Pit--Claudel]

[-- Attachment #1.1: Type: text/plain, Size: 2067 bytes --]

On 2016-07-04 12:39, Clément Pit--Claudel wrote:
> Hi emacs-devel,
> 
> As a prelude to implementing the actual functionality, I'd like to get a clearer picture of what use cases exist for post-redisplay hooks.

Summarizing the current discussion:

(1) Is still valid, though Richard did suggest that we could have Emacs take the screenshots itself. It would indeed be a useful feature to have, though it is partly orthogonal, and seems non-trivial to implement. Richard also suggested special casing this feature and implementing only that instead of a post-display-hook.

(2) Does not sound like it would benefit significantly from such a hook (but I may have missed something).

(3) Does not resolve to something concrete.

Clément.

> Here are the ones that I'm currently aware of; can you think of other ones?
> 
> 1. (my own) Generating emacs screenshots. You can see a demo at http://web.mit.edu/cpitcla/www/emacs-screencast-annot.gif (let me know what you think!). Other hooks do not work because:
>   - pre-redisplay-functions are called too early
>   - pre- and post-command-hook do not run often enough (in the screencast above, see the butterfly animation, for example)
>   - window-related hooks do not run often enough either
>   - redisplay-end-trigger-functions are tricky to use, and deprecated
> 
> 2. (Keith David Bershatsky + Michael Heerdegen @ https://lists.gnu.org/archive/html/bug-gnu-emacs/2016-01/msg01013.html) Updating overlays after scrolling.  The bug thread is pretty long and subtle, but this issue has also been discussed on emacs.stackexchanged IIRC.
> 
> 3. (Stefan? @ https://lists.gnu.org/archive/html/emacs-devel/2009-02/msg00785.html) Running code every time "something visible" happens (e.g. due to process filters)
> 
> For number 1, and potentially number 3, a hook that run after redisplay completes entirely would work. For number 2, things are less clear. Michael, Keith, and Eli, do you have ideas of when in the display cycle such a hook should run?
> 
> Thanks!
> Clément.
> 
> 



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: Use cases for post-redisplay hooks

[Stefan Monnier]

> Summarizing the current discussion:
>
> (1) Is still valid, though Richard did suggest that we could have Emacs take
> the screenshots itself. It would indeed be a useful feature to have, though
> it is partly orthogonal, and seems non-trivial to implement. Richard also
> suggested special casing this feature and implementing only that instead
> of a post-display-hook.
>
> (2) Does not sound like it would benefit significantly from such a hook (but
> I may have missed something).
>
> (3) Does not resolve to something concrete.

On a related note, there could be some use for some kind of
"post-redisplay-hook" in follow-mode.  But it wouldn't just be
`post-redisplay-hook': it would need some way to control also the order
in which windows are redisplayed, and it would have to be run "between
windows" (at the end of computing the new matrices for a window).

The way I imagine this could work is by turning "redisplay" into an
Elisp function which internally would use some lower-level C functions
such as `recompute-matrices-of-window', `update-display-for-window`,
`update-display-for-frame`, and `find-windows-needing-redisplay`.

There would also be a need to control what happens when point needs to
be moved, or when scrolling is needed.
E.g. recompute-matrices-of-window could signal an error of some sort if
point is not within the window, and then `redisplay' could react to such
an error by either moving point or calling `window-try-scrolling'
if/when applicable.


        Stefan