Changeset 77236 in vbox for trunk/include/iprt/sg.h

Timestamp:

Feb 9, 2019 6:30:19 PM (6 years ago)

Author:

vboxsync

Message:

IPRT: Implemented RTFileSgWriteAt and RTfileSgReadAt for linux and freebsd. Clearified RTFileWriteAt and RTFileSgWriteAt specs wrt RTFILE_O_APPEND. bugref:9172

File:

• trunk/include/iprt/sg.h (modified) (6 diffs)

trunk/include/iprt/sg.h

@@ -33 +33 @@
 
 RT_C_DECLS_BEGIN
+
+/** @defgroup grp_rt_sgbuf  RTSgBuf - Scatter / Gather Buffers
+ * @ingroup grp_rt
+ * @{
+ */
 
 /**
@@ -55 +60 @@
  *
  * The members should be treated as private.
+ *
+ * @warning There is a lot of code, especially in the VFS area of IPRT, that
+ *          totally ignores the idxSeg, pvSegCur and cbSegLeft members!  So,
+ *          it is not recommended to pass buffers that aren't fully reset or
+ *          where cbSegLeft is shorter than what paSegs describes.
  */
 typedef struct RTSGBUF
@@ -62 +72 @@
     /** Number of segments. */
     unsigned  cSegs;
+
     /** Current segment we are in. */
     unsigned  idxSeg;
@@ -76 +87 @@
 typedef PRTSGBUF *PPRTSGBUF;
 
+
+/**
+ * Sums up the length of all the segments.
+ *
+ * @returns The complete segment length.
+ * @param   pSgBuf      The S/G buffer to check out.
+ */
+DECLINLINE(size_t) RTSgBufCalcTotalLength(PCRTSGBUF pSgBuf)
+{
+    size_t   cb = 0;
+    unsigned i  = pSgBuf->cSegs;
+    while (i-- > 0)
+        cb += pSgBuf->paSegs[i].cbSeg;
+    return cb;
+}
+
+/**
+ * Sums up the number of bytes left from the current position.
+ *
+ * @returns Number of bytes left.
+ * @param   pSgBuf      The S/G buffer to check out.
+ */
+DECLINLINE(size_t) RTSgBufCalcLengthLeft(PCRTSGBUF pSgBuf)
+{
+    size_t   cb = pSgBuf->cbSegLeft;
+    unsigned i  = pSgBuf->cSegs;
+    while (i-- > pSgBuf->idxSeg + 1)
+        cb += pSgBuf->paSegs[i].cbSeg;
+    return cb;
+}
+
+/**
+ * Checks if the current buffer position is at the start of the first segment.
+ *
+ * @returns true / false.
+ * @param   pSgBuf      The S/G buffer to check out.
+ */
+DECLINLINE(bool) RTSgBufIsAtStart(PCRTSGBUF pSgBuf)
+{
+    return pSgBuf->idxSeg == 0
+        && (   pSgBuf->cSegs == 0
+            || pSgBuf->pvSegCur == pSgBuf->paSegs[0].pvSeg);
+}
+
+/**
+ * Checks if the current buffer position is at the end of all the segments.
+ *
+ * @returns true / false.
+ * @param   pSgBuf      The S/G buffer to check out.
+ */
+DECLINLINE(bool) RTSgBufIsAtEnd(PCRTSGBUF pSgBuf)
+{
+    return pSgBuf->idxSeg > pSgBuf->cSegs
+        || (   pSgBuf->idxSeg == pSgBuf->cSegs
+            && pSgBuf->cbSegLeft == 0);
+}
+
+/**
+ * Checks if the current buffer position is at the start of the current segment.
+ *
+ * @returns true / false.
+ * @param   pSgBuf      The S/G buffer to check out.
+ */
+DECLINLINE(bool) RTSgBufIsAtStartOfSegment(PCRTSGBUF pSgBuf)
+{
+    return pSgBuf->idxSeg < pSgBuf->cSegs
+        && pSgBuf->paSegs[pSgBuf->idxSeg].pvSeg == pSgBuf->pvSegCur;
+}
+
 /**
  * Initialize a S/G buffer structure.
@@ -84 +164 @@
  * @param   cSegs     Number of segments in the array.
  *
- * @note paSegs and cSegs can be NULL and 0 respectively to indicate
- *       an empty S/G buffer. All operations on the S/G buffer will
- *       not do anything in this case.
+ * @note paSegs and cSegs can be NULL and 0 respectively to indicate an empty
+ *       S/G buffer.  Operations on the S/G buffer will not do anything in this
+ *       case.
  */
 RTDECL(void) RTSgBufInit(PRTSGBUF pSgBuf, PCRTSGSEG paSegs, size_t cSegs);
@@ -109 +189 @@
  */
 RTDECL(void) RTSgBufClone(PRTSGBUF pSgBufNew, PCRTSGBUF pSgBufOld);
+
+/**
+ * Returns the next segment in the S/G buffer or NULL if no segments left.
+ *
+ * @returns Pointer to the next segment in the S/G buffer.
+ * @param   pSgBuf      The S/G buffer.
+ * @param   cbDesired   The max number of bytes to get.
+ * @param   pcbSeg      Where to store the size of the returned segment, this is
+ *                      equal or smaller than @a cbDesired.
+ *
+ * @note    Use RTSgBufAdvance() to advance after read/writing into the buffer.
+ */
+DECLINLINE(void *) RTSgBufGetCurrentSegment(PRTSGBUF pSgBuf, size_t cbDesired, size_t *pcbSeg)
+{
+    if (!RTSgBufIsAtEnd(pSgBuf))
+    {
+        *pcbSeg = RT_MIN(cbDesired, pSgBuf->cbSegLeft);
+        return pSgBuf->pvSegCur;
+    }
+    *pcbSeg = 0;
+    return NULL;
+}
 
 /**