[libvirt] [PATCH v2 13/38] Introduce VIR_STREAM_RECV_STOP_AT_HOLE flag

[John Ferlan]

On 04/20/2017 06:01 AM, Michal Privoznik wrote:
> This flag is for virStreamRecvFlags API. Its purpose is to stop
> reading from the stream if a hole occurred as holes are to be
> threated separately.

Consider:

Add a new flag to virStreamRecvFlags in order to handle being able to
stop reading from the stream so that the consumer can generate a "hole"
in stream target. Generation of a hole replaces the need to receive and
handle a sequence of zero bytes for sparse stream targets.


> 
> Signed-off-by: Michal Privoznik <mprivozn at redhat.com>
> ---
>  include/libvirt/libvirt-stream.h |  4 ++++
>  src/libvirt-stream.c             | 30 +++++++++++++++++++++++++++++-
>  2 files changed, 33 insertions(+), 1 deletion(-)
> 
> diff --git a/include/libvirt/libvirt-stream.h b/include/libvirt/libvirt-stream.h
> index 2ebda74..23fcc26 100644
> --- a/include/libvirt/libvirt-stream.h
> +++ b/include/libvirt/libvirt-stream.h
> @@ -45,6 +45,10 @@ int virStreamRecv(virStreamPtr st,
>                    char *data,
>                    size_t nbytes);
>  
> +typedef enum {
> +    VIR_STREAM_RECV_STOP_AT_HOLE = (1 << 0),
> +} virStreamRecvFlagsValues;
> +
>  int virStreamRecvFlags(virStreamPtr st,
>                         char *data,
>                         size_t nbytes,
> diff --git a/src/libvirt-stream.c b/src/libvirt-stream.c
> index 3ac9e0d..1162d33 100644
> --- a/src/libvirt-stream.c
> +++ b/src/libvirt-stream.c
> @@ -290,7 +290,7 @@ virStreamRecv(virStreamPtr stream,
>   * @stream: pointer to the stream object
>   * @data: buffer to read into from stream
>   * @nbytes: size of @data buffer
> - * @flags: extra flags; not used yet, so callers should always pass 0
> + * @flags: bitwise-OR of virStreamRecvFlagsValues
>   *
>   * Reads a series of bytes from the stream. This method may
>   * block the calling application for an arbitrary amount
> @@ -301,6 +301,29 @@ virStreamRecv(virStreamPtr stream,
>   * nbytes, 0) is equivalent to calling virStreamRecv(stream,
>   * data, nbytes) and vice versa.
>   *
> + * If flag VIR_STREAM_RECV_STOP_AT_HOLE is set, this function
> + * will stop reading from stream if it has reached a hole. In
> + * that case, -3 is returned and virStreamHoleSize() should be

Obvious API name impact from patch 11/12...

Consider perhaps VIR_STREAM_RECV_HANDLE_SPARSE - or something that
indicates sparse management.

> + * called to get the hole size. An example using this flag might
> + * look like this:
> + *
> + * while (1) {
> + *   char buf[4096];
> + *
> + *   int ret = virStreamRecvFlags(st, buf, len, VIR_STREAM_STOP_AT_HOLE);
> + *   if (ret < 0) {
> + *     if (ret == -3) {
> + *       unsigned long long len;
> + *       ret = virStreamHoleSize(st, &len);

  ...if ((ret = vir*()) < 0)
        report error

? IDC exactly, just noting.

> + *       ...seek len bytes in target...
> + *     } else {
> + *       return -1;
> + *     }
> + *   } else {
> + *       ...write buf to target...
> + *   }
> + * }

The entire code snippet needs an extra space indent; otherwise, it
doesn't look right on the generated web page.

I would think this is ACK-able w/ the minor adjustments - there could be
side effects from previous adjustments though.

John
> + *
>   * Returns 0 when the end of the stream is reached, at
>   * which time the caller should invoke virStreamFinish()
>   * to get confirmation of stream completion.
> @@ -311,6 +334,9 @@ virStreamRecv(virStreamPtr stream,
>   *
>   * Returns -2 if there is no data pending to be read & the
>   * stream is marked as non-blocking.
> + *
> + * Returns -3 if there is a hole in stream and caller requested
> + * to stop at a hole.
>   */
>  int
>  virStreamRecvFlags(virStreamPtr stream,
> @@ -332,6 +358,8 @@ virStreamRecvFlags(virStreamPtr stream,
>          ret = (stream->driver->streamRecvFlags)(stream, data, nbytes, flags);
>          if (ret == -2)
>              return -2;
> +        if (ret == -3)
> +            return -3;
>          if (ret < 0)
>              goto error;
>          return ret;
>