bug#13400: 23.4; overlapping process filter calls

[Hendrik Tews]

Noam,

thanks for addressing this quite old bug report. I do have some
comments:

Noam Postavsky <npostavs@gmail.com> writes:

> Hendrik Tews <hendrik@askra.de> writes:
>
>> because Stefan Monnier asked for it
>> (http://lists.inf.ed.ac.uk/pipermail/proofgeneral-devel/2013/000296.html)
>
> [Note: meanwhile the section number has changed to 38 instead of 37.]
>
>> - Section "37.9 Receiving Output from Processes" does not list
>>   process-send-string. How about other blocking I/O functions?
>
> In the attached patch, I've added a mention/xref for functions which send
> data to processes.

How about other blocking I/O functions? When output is accepted
inside process-send-string, then it probably is in all
potentially blocking I/O functions? The list of functions in 38.9
after "Output from a subprocess can arrive only" should be
complete. If the programmer cannot rely on the documentation to
be complete here, he or she has no other choice than to assume
that output can arrive anywhere and he/she _is_ plagued with the
usual parallel programming problems.

Therefore, please make a careful investigation to ensure that the
list of functions in which output can arrive is _really_ complete
in the documentation.

>> - Same in "37.9.2. Process Filter Functions"
>
> This section is repeated twice (I addressed the second instance below).

I mentioned this section twice, because there are _two_
documentation problems. I really believe you should address both
and not just one. The first problem in 38.9.2 is the same as
above: The list of functions after "The filter function can only
be called" is far from complete.

The second problem is that it does not document the possibility
of recursive filter calls.

>> - Same in "37.4 Creating an Asynchronous Process" ,
>>   process-send-string is neither waiting for input not time
>>   delay.
>
> I don't see any mention of process-send-string in that section, nor how
> it's relevant to the rest of this report.

Come on, please read that section carefully. "Emacs accepts data
from the process only while waiting for input or for a time
delay" in there implies that Emacs is _not_ accepting data during
process-send-string, because, as I wrote, 

>>   process-send-string is neither waiting for input no[r] time
>>   delay.

Therefore, this section implies that Emacs is _not_ accepting
data during process-send-string. If it does, it is a bug.

>> - "37.7 Sending Input to Processes" says that filters can run
>>   inside process-send-string, but it could be clearer about the
>>   point that this can also happen inside the same filter for the
>>   same process.
>
> I'm not really convinced that is necessary.

It is about a few words making the documentation more precise,
potentially saving somebody a painful debugging session of
several hours - similar to what I went through in 2013. Back
then, I was lucky because clearing the disk caches was enough to
reproduce the problem. Today with SSD's it is probably much
harder...

Adding to the original bug report, I would suggest to restructure
the documentation, such that there is only one section
documenting all the functions in which process output could
arrive and such that all the other sections only refer to that
section. It should really not be the case that different sections
make different and sometimes inconsistent statements about the
same feature.

Hendrik