[libvirt] [PATCH v3 05/31] Introduce virStreamSendHole

[John Ferlan]

On 05/16/2017 10:03 AM, Michal Privoznik wrote:
> This API is used to tell the other side of the stream to skip
> some bytes in the stream. This can be used to create a sparse
> file on the receiving side of a stream.
> 
> It takes @length argument, which says how big the hole is. This
> skipping is done from the current point of stream. Since our
> streams are not rewindable like regular files, we don't need
> @whence argument like seek(2) has.
> 
> Signed-off-by: Michal Privoznik <mprivozn at redhat.com>
> ---
>  include/libvirt/libvirt-stream.h |  4 +++
>  src/driver-stream.h              |  6 ++++
>  src/libvirt-stream.c             | 61 ++++++++++++++++++++++++++++++++++++++++
>  src/libvirt_public.syms          |  1 +
>  4 files changed, 72 insertions(+)
> 

[...]

> diff --git a/src/libvirt-stream.c b/src/libvirt-stream.c
> index 7535deb3c..a09896dcd 100644
> --- a/src/libvirt-stream.c
> +++ b/src/libvirt-stream.c
> @@ -344,6 +344,67 @@ virStreamRecvFlags(virStreamPtr stream,
>  }
>  
>  
> +/**
> + * virStreamSendHole:
> + * @stream: pointer to the stream object
> + * @length: number of bytes to skip
> + * @flags: extra flags; not used yet, so callers should always pass 0
> + *
> + * Rather than transmitting empty file space, this API directs
> + * the @stream target to create @length bytes of empty space.
> + * This API would be used when uploading or downloading sparsely
> + * populated files to avoid the needless copy of empty file
> + * space.
> + *
> + * An example using this with a hypothetical file upload API
> + * looks like:
> + *
> + *   virStream st;
> + *
> + *   while (1) {
> + *     char buf[4096];
> + *     size_t len;
> + *     if (..in hole...) {
> + *       ..get hole size...
> + *       virStreamSendHole(st, len, 0);
> + *     } else {
> + *       ...read len bytes...
> + *       virStreamSend(st, buf, len);
> + *     }
> + *   }
> + *
> + * Returns 0 on success,
> + *        -1 error
> + */
> +int
> +virStreamSendHole(virStreamPtr stream,
> +                  long long length,
> +                  unsigned int flags)
> +{
> +    VIR_DEBUG("stream=%p, length=%lld flags=%x",
> +              stream, length, flags);
> +
> +    virResetLastError();
> +
> +    virCheckStreamReturn(stream, -1);

Perhaps some preventative programming:

    virCheckNonNegativeArgGoto(length, error);

Although that would mean calling virDispatchError unless there was some
sort of virCheck*ArgReturn(length, -1)

Reviewed-by: John Ferlan <jferlan at redhat.com>


John

[...]