[libvirt] [PATCH v3 07/31] Introduce VIR_STREAM_RECV_STOP_AT_HOLE flag
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(a)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...
+ * }
+ * } else {
+ * return -1;
+ * }
+ * } else {
+ * ...write buf to target...
+ * }
+ * }
+ *
* Returns 0 when the end of the stream is reached, at
* which time the caller should invoke virStreamFinish()
* to get confirmation of stream completion.
@@ -310,6 +337,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,
@@ -331,6 +361,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;
--
2.13.0