[pulseaudio-discuss] [PATCH] stream: fix incorrect doc for pa_stream_writable_size()

[Arun Raghavan]

On 11 January 2016 at 18:58, Tanu Kaskinen <tanuk at iki.fi> wrote:
> The old documentation implied that it wouldn't be possible to write
> more than the returned amount, which was incorrect.
> ---
>  src/pulse/stream.h | 9 ++++++++-
>  1 file changed, 8 insertions(+), 1 deletion(-)
>
> diff --git a/src/pulse/stream.h b/src/pulse/stream.h
> index 70fa415..802660d 100644
> --- a/src/pulse/stream.h
> +++ b/src/pulse/stream.h
> @@ -588,7 +588,14 @@ int pa_stream_peek(
>   * calling pa_stream_peek(). */
>  int pa_stream_drop(pa_stream *p);
>
> -/** Return the number of bytes that may be written using pa_stream_write(). */
> +/** Return the number of bytes that the server has requested to be written.
> + *
> + * Contrary to what might be expected from the function name, it's usually
> + * possible to write more than the returned amount, but typically it doesn't
> + * make sense to do that, because that will likely make the stream latency
> + * exceed the target latency (which is configured with the tlength parameter in
> + * pa_buffer_attr).
> + */
>  size_t pa_stream_writable_size(pa_stream *p);
>
>  /** Return the number of bytes that may be read using pa_stream_peek(). */
> --

I would rewrite this as:

"
Return the number of bytes requested by the server that have not yet
been written.

It is possible to write more than this amount, up to the stream's
buffer_attr.maxlength bytes. This is usually not desirable, though, as
it would increase stream latency to be higher than requested
(buffer_attr.tlength).
"

-- Arun