accept-process-output doc string vs. lispref

accept-process-output doc string vs. lispref

[Kim F. Storm]

There is a _BIG_ problem between the doc string and lispref 
for the accept-process-output function:

DOC STRING:

(accept-process-output &optional process timeout timeout-msecs just-this-one)
..
Non-nil second arg timeout and third arg timeout-msecs are number of
seconds and microseconds to wait; return after that much time whether
or not there is input.

LISP REF:

 - Function: accept-process-output &optional process seconds millisec just-this-one

     The arguments SECONDS and MILLISEC let you specify timeout
     periods.  The former specifies a period measured in seconds and the
     latter specifies one measured in milliseconds.  The two time
     periods thus specified are added together, and
     `accept-process-output' returns after that much time whether or
     not there has been any subprocess output.


So doc string says that "timeout-msecs" is in MICRO seconds, while
the lisp ref says "millisec" is in MILLI seconds.

The doc string has been like that since 1991, and the lisp ref since 1994.

The C-code interprets it as MICRO seconds, so the doc string is correct.

However, the name of the parameter "msecs" is misleading.


I also checked Xemacs, and it interprets the argument as MILLI seconds.


The recently reported problem with gnus looping in gettimeofday and
accept-process-output (IIRC) can probably be attributed to gnus
using a timeout on accept-process-output of msec=100, i.e. 0.0001 second.

Looking at the code, it clearly expects the arg to be interpreted as
100 MILLI seconds.  I have also checked all other uses of
accept-process-output, and all code that sets timeout-msec expects it
to be MILLI seconds.

On Linux [the kernel], the minimum time-difference is typically 0.01
second, so having a resolution in MICRO seconds is pretty useless;
MILLI seconds is fully adequate


I will change the interpretation from MICRO to MILLI seconds to align
the code and doc string with 1) the LISP REF, and 2) all uses of the
function.

--
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: accept-process-output doc string vs. lispref

[Stefan Monnier]

> I will change the interpretation from MICRO to MILLI seconds to align
> the code and doc string with 1) the LISP REF, and 2) all uses of the
> function.

While you're there, plase make it possible to use a float for `timeout', as
is done in sit-for.


        Stefan

Re: accept-process-output doc string vs. lispref

[Kim F. Storm]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> I will change the interpretation from MICRO to MILLI seconds to align
>> the code and doc string with 1) the LISP REF, and 2) all uses of the
>> function.
>
> While you're there, plase make it possible to use a float for `timeout', as
> is done in sit-for.

I will do that.  

The LISPREF already says this is possible -- it did so 16 years ago :-)

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: accept-process-output doc string vs. lispref

[Kim F. Storm]

storm@cua.dk (Kim F. Storm) writes:

> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
>>> I will change the interpretation from MICRO to MILLI seconds to align
>>> the code and doc string with 1) the LISP REF, and 2) all uses of the
>>> function.
>>
>> While you're there, plase make it possible to use a float for `timeout', as
>> is done in sit-for.
>
> I will do that.  
>
> The LISPREF already says this is possible -- it did so 16 years ago :-)

I have installed the changes.


-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk