[libvirt] [PATCH v3 07/31] Introduce VIR_STREAM_RECV_STOP_AT_HOLE flag

[Michal Privoznik]

On 05/16/2017 11:22 PM, John Ferlan wrote:
> 
> 
> On 05/16/2017 10:03 AM, Michal Privoznik wrote:
>> 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             | 34 +++++++++++++++++++++++++++++++++-
>>  2 files changed, 37 insertions(+), 1 deletion(-)
>>
>> diff --git a/include/libvirt/libvirt-stream.h b/include/libvirt/libvirt-stream.h
>> index feaa8ad64..c4baaf7a3 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 dc0dc9ea3..bedb6159a 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
>> @@ -300,6 +300,33 @@ virStreamRecv(virStreamPtr stream,
>>   * @flags. Calling this function with no @flags set (equal to
>>   * zero) is equivalent to calling virStreamRecv(stream, data, nbytes).
>>   *
>> + * 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 virStreamRecvHole() should be
>> + * 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) {
>> + *         long long len;
>> + *         ret = virStreamRecvHole(st, &len, 0);
>> + *         if (ret < 0) {
>> + *           ...error..
>> + *         } else {
>> + *           ...seek len bytes in target...
> 
> Do/should we care to point out that @len is a "long long" and seeking is
> done in chunks of "off_t"?

Not really. This is just an example - anybody can understand that.

Michal