bug#22404: 25.1.50; Forcing `window-scroll-functions` to run.

[Keith David Bershatsky]

I have a minor mode that draws overlays from `window-start` to `window-end`, 
and those two values are mission critical to making sure that the overlays are 
placed correctly.  I have `word-wrap` set to `t`.  I have a function that makes 
relevant calculations in the visible window, which begins at `window-start` and 
uses `vertical-motion` for every visual line until `window-end`.  Along the 
way, I gather 22 different elements of a list for EACH visible line:  points at 
the beginning/ending of visual line (pbovl/peovl); points at beginning/ending 
of full line (bol/eol); column at the end of visual line (col-at-eovl); line 
number `(format-mode-line "%l")`; and all of the following in a vertical line 
(from top to bottom of the window) where the cursor is:  column, point, 
character, foreground/background colors of character.

When the list is assembled, I then take that list and place overlays to create 
a horizontal and vertical line compatible with `word-wrap` -- the result is a 
visual cross-hairs spanning the entire length and width of the visible window.  
I am using XPM images for the vertical line, which permits me to achieve a thin 
vertical line to the left of each character -- it looks just like a thin vbar 
cursor.  I control the color of the vertical line -- the letters remain the 
same color they were, but the line color varies -- yellow for even column 
number; red for odd column number; green for when I am beyond the fill-column 
on the first visual line; a medium blue for a line that is visually wrapped 
when point is on a visual line subsequent to the first wrapped line; and a cyan 
color when point is at the right window boundary.  The horizontal line 
stretches the entire length of the window, even for the word-wrapped lines.  I 
have some fancy XPM images that change depending upon where point is.  It works 
with active regions too.  I have line numbering (in the left-hand margin) for 
each line.  I placer certain bitmap images in the right fringe depending when 
point is at the last character at the window edge, or when there is a hard 
return at the right window edge.  Each line-end (eol) has a pilcrow symbol that 
is XPM, except when cursor is at eol, in which case it is a different XPM 
image.  The end of the buffer has a different XPM image and the vertical line 
extends to the last visual line, even if the point at the end of the buffer is 
a few inches to the left of the vertical line.

The calculations (primarily because of `vertical-motion`) are too costly 
time-wise to perform more than once during each command loop because it slows 
down performance.

If I run the calculations from the `post-command-hook`, I will have wasted 
precious time IF the `window-scroll-functions` hook will be running.  IF the 
`window-scroll-functions` hook will be running, then the `window-start` and 
`window-end` obtained from the `post-command-hook` will be wrong -- so there is 
no point using those PCH wrong numbers.

If I run the calculations from the INITIAL run of the `window-scroll-functions` 
hook, I will have wasted precious time IF the WSF hook will be running a SECOND 
time.  [WSF runs a SECOND time if point was PARTIALLY visible.]  IF the WSF 
will be running more than one time, then the INITIAL values for `window-start` 
and `window-end` will be wrong -- so there is no point using those WSF wrong 
numbers.  Instead, I have to wait until the LAST call on the WSF when the final 
correct values for `window-start` and `window-end` can be truly ascertained.

Without the benefit of feature request 22404, there are a couple of options 
that are not ideal.

OPTION # 1(a):  Devise an efficient/accurate test that can be called from the 
`post-command-hook` to ascertain whether the `window-scroll-functions` hook 
will be running one or more times.  [Without a forced trigger, WSF only runs 
SOME of the time.]  If the WSF will be running one or more times, then do NOT 
perform the overlay calculations because the PCH values for `window-start` and 
`window-end` are wrong.  If the WSF will NOT be running, then go ahead and 
perform the time-costly calculations and place the overlays immediately.

OPTION # 1(b):  When the `window-scroll-functions` hook runs, I need to figure 
out whether it will be running one more time (subsequently) because point was 
only partially visible.  The only test I am aware of is 
`(pos-visible-in-window-p nil nil nil)`.  The LAST call on the WSF is the 
mission critical because that produces the correct values for `window-start` 
and `window-end`.  If WSF will only be running once, then go ahead and perform 
the time-costly calculations and place the overlays immediately.  If the WSF 
will be running more than once, then the *initial* WSF values for `window-start 
and `window-end` are wrong -- in that case, wait until the last call of WSF to 
perform the calculations and place overlays.

OPTION # 2:  Call `set-window-buffer` from the `post-command-hook` as a means 
of forcing WSF to run during the latter part of redisplay.  In this case, we 
never use the PCH values of `window-start` and `window-end` -- instead, we wait 
for WSF to give us the correct values.  This solution is not preferred because 
`set-window-buffer` was not designed to be used solely as a WSF trigger.  In 
the context of my example, I don't need to set the window buffer and I don't 
need to run the `window-configuration-change-hook` -- I just want to force WSF 
to run during the latter part of redisplay.

OPTION # 3:  Trigger the WSF without all the hoopla -- e.g., 
w->optional_new_start = true;.  E.g., my sample C-function `force_wsf`.

OPTION # 4 (ideal):  Create an entirely new animal that knows whether WSF will 
run more than once, and only produces the correct values for `window-start` and 
`window-end` in ALL circumstances, and then permits the user to run a custom 
function that takes advantage of those values.

Thanks,

Keith