pow.3: Add note on performance characteristics of pow

  Hello,

This patch documents
https://sourceware.org/bugzilla/show_bug.cgi?id=13932 as requested in
https://sourceware.org/bugzilla/show_bug.cgi?id=15267. It would be
nice to add more details, but it seems the behavior and its
consequences is not well understood. The purpose of the note is to
warn users of this behavior and thus avoid frustration
(http://entropymine.com/imageworsener/slowpow/).

This is my first patch. I followed (hopefully correctly) the instructions here:
https://www.kernel.org/doc/man-pages/patches.html

Cheers,

Manuel.
  

Hello Manuel,


On 10/17/2014 01:51 AM, Manuel López-Ibáñez wrote:
> Hello,
> 
> This patch documents
> https://sourceware.org/bugzilla/show_bug.cgi?id=13932 as requested in
> https://sourceware.org/bugzilla/show_bug.cgi?id=15267. It would be
> nice to add more details, but it seems the behavior and its
> consequences is not well understood. The purpose of the note is to
> warn users of this behavior and thus avoid frustration
> (http://entropymine.com/imageworsener/slowpow/).
> 
> This is my first patch. I followed (hopefully correctly) the instructions here:
> https://www.kernel.org/doc/man-pages/patches.html


Thanks for this patch. It looks good. But inline patches are easier to review.
One small question below.

> diff --git a/man3/pow.3 b/man3/pow.3
> index d0a2ea8..3d2151a 100644
> --- a/man3/pow.3
> +++ b/man3/pow.3
> @@ -320,6 +320,17 @@ The variant returning
>  also conforms to
>  SVr4, 4.3BSD, C89.
>  .SH BUGS
> +On 64-bits,
> +.\"
> +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=13932
> +.BR pow ()
> +may be more than 10,000 times slower for some inputs than for other nearby

I plan to change "some" to "some (rare)". Sound okay? The point is not to
worry people that this is a problem that is commonly encountered. (Or is it?)

Thanks,

Michael

> +inputs. The inputs that produce such behavior are different for
> +.BR powf (),
> +.BR pow ()
> +and
> +.BR powl ().
> +
>  In glibc 2.9 and earlier,
>  .\"
>  .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6776
  

On Fri, Oct 17, 2014 at 07:24:38AM +0200, Michael Kerrisk (man-pages) wrote:
> > diff --git a/man3/pow.3 b/man3/pow.3
> > index d0a2ea8..3d2151a 100644
> > --- a/man3/pow.3
> > +++ b/man3/pow.3
> > @@ -320,6 +320,17 @@ The variant returning
> >  also conforms to
> >  SVr4, 4.3BSD, C89.
> >  .SH BUGS
> > +On 64-bits,
> > +.\"
> > +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=13932
> > +.BR pow ()
> > +may be more than 10,000 times slower for some inputs than for other nearby
> 
> I plan to change "some" to "some (rare)". Sound okay? The point is not to
> worry people that this is a problem that is commonly encountered. (Or is it?)

Rare is OK, these points don't occur very frequently.

> > +inputs. The inputs that produce such behavior are different for
> > +.BR powf (),
> > +.BR pow ()
> > +and
> > +.BR powl ().
> > +

The slow fallback is only taken for pow, not powf or powl.

Siddhesh