Example: Fix the previous commit.

[libucw.git] / ucw / fastbuf.h

diff --git a/ucw/fastbuf.h b/ucw/fastbuf.h
index e74034f44d2dcc4c7c519ee44ec2188a19ccd8af..d0cf30cad3415f655ba12516ac66a4feab50d7fd 100644 (file)
--- a/ucw/fastbuf.h
+++ b/ucw/fastbuf.h
@@ -19,51 +19,97 @@
  *
  * Generally speaking, a fastbuf consists of a buffer and a set of callbacks.
  * All front-end functions operate on the buffer and if the buffer becomes
  *
  * Generally speaking, a fastbuf consists of a buffer and a set of callbacks.
  * All front-end functions operate on the buffer and if the buffer becomes

- * empty or fills up, they ask the corresponding callback to solve the
+ * empty or fills up, they ask the corresponding callback to handle the

  * situation. Back-ends then differ just in the definition of the callbacks.
  * situation. Back-ends then differ just in the definition of the callbacks.

- * The state of the fastbuf is represented by `struct fastbuf`, which
- * is a simple structure describing the state of the buffer and pointers
- * to the callback functions.
- *
- * When we are reading from the fastbuf, the buffer is laid out as follows:
- *
- *  +----------------+---------------------------+
- *  | read data      | free space                |
- *  +----------------+---------------------------+
- *  ^        ^        ^                           ^
- *  buffer   bptr     bstop                       bufend
- *
- * Here `bptr` points to the next character to be read. After the last character is
- * read, `bptr == bstop` and the `refill` callback gets called upon the next read
- * attempt to bring further data. This gives us an easy way how to implement @bungetc().
- *
- * When writing, the situation looks like:
- *
- *  +--------+--------------+--------------------+
- *  | unused | written data | free space         |
- *  +--------+--------------+--------------------+
- *  ^         ^              ^                    ^
- *  buffer    bstop          bptr                 bufend
- *
- * In this case, the `bptr` points at the position where the next character
- * will be written to. When we want to write, but `bptr == bufend`, we call
- * the `spout` hook to flush the data and get an empty buffer.
- *
- * Several dirty tricks can be played:
- *
- *    - The `spout`/`refill` hooks can change not only `bptr` and `bstop`, but also
- *     the location and size of the buffer; the fb-mem back-end takes advantage of it.
- *    - In some cases, the user of the `bdirect` interface can be allowed to modify
- *     the data in the buffer to avoid unnecessary copying. If the back-end
- *     allows such modifications, it can set `fastbuf->can_overwrite_buffer` accordingly:
- *             *  0 if no modification is allowed,
- *             *  1 if the user can modify the buffer on the condition that
- *                  the modifications will be undone before calling the next
- *                  fastbuf operation
- *             *  2 if the user is allowed to overwrite the data in the buffer
- *                  if @bdirect_read_commit_modified() is called afterwards.
- *                  In this case, the back-end must be prepared for trimming
- *                  of the buffer which is done by the commit function.
+ *
+ * The state of the fastbuf is represented by a `struct fastbuf`, which
+ * is a simple structure describing the state of the buffer (the pointers
+ * `buffer`, `bufend`), two front-end cursors (`bptr`, `bstop`), position in the file (`pos`)
+ * and pointers to the callback functions.
+ *
+ * The buffer can be in one of the following states:
+ *
+ * 1. Flushed:
+ *
+ *    +----------------+---------------------------+
+ *    | unused         | free space                |
+ *    +----------------+---------------------------+
+ *    ^                ^                           ^
+ *    buffer        <= bptr == bstop (pos)      <= bufend
+ *
+ *   * If `bptr == bstop`, then there is no cached data and
+ *     the fastbuf is ready for any read or write operation.
+ *     Position of the back-end's cursor equals the front-end's one.
+ *   * The interval `[bstop, bufend]` can be used by front-ends
+ *     for writing. If it is empty, the `spout` callback gets called
+ *     upon the first write attempt to allocate a new buffer.
+ *   * When a front-end needs to read something, it calls the `spout` callback.
+ *   * Any of the pointers can be NULL.
+ *
+ * 2. Reading:
+ *
+ *    +----------------+---------------------------+
+ *    | read data      | unused                    |
+ *    +----------------+---------------------------+
+ *    ^         ^      ^                           ^
+ *    buffer <= bptr <= bstop (pos)             <= bufend
+ *
+ *   * If we try to read something, we get to the reading mode.
+ *   * No writing is allowed until a flush operation. But note that @bflush()
+ *     will simply set `bptr` to `bstop` and it breaks the position of the front-end's cursor.
+ *   * The interval `[buffer, bstop]` contains a block of data read by the back-end.
+ *     `bptr` is the front-end's cursor which points to the next character to be read.
+ *     After the last character is read, `bptr == bstop` and the `refill` callback
+ *     gets called upon the next read attempt to bring further data.
+ *     This gives us an easy way how to implement @bungetc().
+ *
+ * 3. Writing:
+ *
+ *    +---------+--------------+-------------------+
+ *    | unused  | written data | free space        |
+ *    +---------+--------------+-------------------+
+ *    ^         ^              ^                   ^
+ *    buffer <= bstop (pos)  < bptr             <= bufend
+ *
+ *   * This schema corresponds to the situation after a write attempt.
+ *   * No reading is allowed until a flush operation.
+ *   * The `bptr` points at the position where the next character
+ *     will be written to. When we want to write, but `bptr == bufend`, we call
+ *     the `spout` hook to flush the data and get an empty buffer.
+ *
+ *
+ * Rules for back-ends:
+ *
+ *   - Front-ends are only allowed to change the value of `bptr`, some flags
+ *     and if a fatal error occurs, then also `bstop`.
+ *   - `buffer <= bstop <= bufend`.
+ *   - `pos` should be the position in the file corresponding of the location of `bstop` in the buffer.
+ *   - Failed callbacks (except `close`) should use @bthrow().
+ *   - Any callback pointers may be NULL in case the callback is not implemented.
+ *   - Callbacks can change not only `bptr` and `bstop`, but also the location and size of the buffer;
+ *     the fb-mem back-end takes advantage of it.
+ *
+ *   - initialization:
+ *     * out: `buffer <= bptr == bstop <= bufend` (flushed)
+ *
+ *   - `refill`:
+ *     * in: `buffer <= bptr == bstop <= bufend` (reading or flushed)
+ *     * out: `buffer <= bptr < bstop <= bufend` (reading)
+ *
+ *   - `spout`:
+ *     * in: `buffer <= bstop <= bptr <= bufend` (writing or flushed)
+ *     * out: `buffer <= bstop <= bufend` (flushed)
+ *     * `bptr` is set automatically to `bstop`.
+ *     * If the input `bptr` equals ` bstop`, then the resulting `bstop` must be lower than `bufend`.
+ *
+ *   - `seek`:
+ *     * in: `buffer <= bstop == bptr <= bufend` (flushed)
+ *     * out: `buffer <= bstop <= bufend` (flushed)
+ *     * `bptr` is set automatically to `bstop`.
+ *
+ *   - `close`:
+ *     * in: `buffer <= bptr == bstop <= bufend` (flushed)
+ *     * `close` must always free all internal structures, even when it throws an exception.

  *
  ***/
 
  *
  ***/
 


@@ -444,12 +490,12 @@ static inline void bputc(struct fastbuf *f, uns c)                /** Write a single character
     bputc_slow(f, c);
 }
 
     bputc_slow(f, c);
 }
 

-static inline uns bavailr(struct fastbuf *f)
+static inline uns bavailr(struct fastbuf *f)                   /** Return the length of the cached data to be read. Do not use directly. **/

 {
   return f->bstop - f->bptr;
 }
 
 {
   return f->bstop - f->bptr;
 }
 

-static inline uns bavailw(struct fastbuf *f)
+static inline uns bavailw(struct fastbuf *f)                   /** Return the length of the buffer available for writing. Do not use directly. **/

 {
   return f->bufend - f->bptr;
 }
 {
   return f->bufend - f->bptr;
 }


@@ -595,10 +641,28 @@ static inline int bskip(struct fastbuf *f, uns len) /** Skip @len bytes without
 }
 
 /*** === Direct I/O on buffers ***/
 }
 
 /*** === Direct I/O on buffers ***/

-// TODO Documentation -- what do they do?

 
 

-static inline uns
-bdirect_read_prepare(struct fastbuf *f, byte **buf)
+/**
+ * Begin direct reading from fastbuf's internal buffer to avoid unnecessary copying.
+ * The function returns a buffer @buf together with its length in bytes (zero means EOF)
+ * with cached data to be read.
+ *
+ * Some back-ends allow the user to modify the data in the returned buffer to avoid unnecessary.
+ * If the back-end allows such modifications, it can set `f->can_overwrite_buffer` accordingly:
+ *
+ *   - 0 if no modification is allowed,
+ *   - 1 if the user can modify the buffer on the condition that
+ *       the modifications will be undone before calling the next
+ *       fastbuf operation
+ *   - 2 if the user is allowed to overwrite the data in the buffer
+ *       if @bdirect_read_commit_modified() is called afterwards.
+ *       In this case, the back-end must be prepared for trimming
+ *       of the buffer which is done by the commit function.
+ *
+ * The reading must be ended by @bdirect_read_commit() or @bdirect_read_commit_modified(),
+ * unless the user did not read or modify anything.
+ **/
+static inline uns bdirect_read_prepare(struct fastbuf *f, byte **buf)

 {
   if (f->bptr == f->bstop && !f->refill(f))
     {
 {
   if (f->bptr == f->bstop && !f->refill(f))
     {


@@ -609,21 +673,33 @@ bdirect_read_prepare(struct fastbuf *f, byte **buf)
   return bavailr(f);
 }
 
   return bavailr(f);
 }
 

-static inline void
-bdirect_read_commit(struct fastbuf *f, byte *pos)
+/**
+ * End direct reading started by @bdirect_read_prepare() and move the cursor at @pos.
+ * Data in the returned buffer must be same as after @bdirect_read_prepare() and
+ * @pos must point somewhere inside the buffer.
+ **/
+static inline void bdirect_read_commit(struct fastbuf *f, byte *pos)

 {
   f->bptr = pos;
 }
 
 {
   f->bptr = pos;
 }
 

-static inline void
-bdirect_read_commit_modified(struct fastbuf *f, byte *pos)
+/**
+ * Similar to @bdirect_read_commit(), but accepts also modified data before @pos.
+ * Note that such modifications are supported only if `f->can_overwrite_buffer == 2`.
+ **/
+static inline void bdirect_read_commit_modified(struct fastbuf *f, byte *pos)

 {
   f->bptr = pos;
   f->buffer = pos;     /* Avoid seeking backwards in the buffer */
 }
 
 {
   f->bptr = pos;
   f->buffer = pos;     /* Avoid seeking backwards in the buffer */
 }
 

-static inline uns
-bdirect_write_prepare(struct fastbuf *f, byte **buf)
+/**
+ * Start direct writing to fastbuf's internal buffer to avoid copy overhead.
+ * The function returns the length of the buffer in @buf (at least one byte)
+ * where we can write to. The operation must be ended by @bdirect_write_commit(),
+ * unless nothing is written.
+ **/
+static inline uns bdirect_write_prepare(struct fastbuf *f, byte **buf)

 {
   if (f->bptr == f->bufend)
     f->spout(f);
 {
   if (f->bptr == f->bufend)
     f->spout(f);


@@ -631,8 +707,12 @@ bdirect_write_prepare(struct fastbuf *f, byte **buf)
   return bavailw(f);
 }
 
   return bavailw(f);
 }
 

-static inline void
-bdirect_write_commit(struct fastbuf *f, byte *pos)
+/**
+ * Commit the data written to the buffer returned by @bdirect_write_prepare().
+ * The length is specified by @pos which must point just after the written data.
+ * Also moves the cursor to @pos.
+ **/
+static inline void bdirect_write_commit(struct fastbuf *f, byte *pos)

 {
   f->bptr = pos;
 }
 {
   f->bptr = pos;
 }