aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2019-09-26 19:18:14 +0200
committerDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2019-09-26 19:22:22 +0200
commitb0d718a4b6628fc9673e2a1e2d26792aae3d0a0d (patch)
treea48c154b94bcf68d63f8505b807540c1c7cfb0f7
parent430e173af5d20ad68f6b5720e6d341b06c5b4858 (diff)
Update documentation on sqfs_data_writer_t
Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>
-rw-r--r--include/sqfs/block.h26
-rw-r--r--include/sqfs/data_writer.h74
2 files changed, 79 insertions, 21 deletions
diff --git a/include/sqfs/block.h b/include/sqfs/block.h
index 0dee934..15d269d 100644
--- a/include/sqfs/block.h
+++ b/include/sqfs/block.h
@@ -37,45 +37,47 @@
typedef enum {
/**
* @brief Only calculate checksum, do NOT compress the data.
+ *
+ * If set, the blocks of a file will not be compressed by the
+ * @ref sqfs_data_writer_t.
*/
SQFS_BLK_DONT_COMPRESS = 0x0001,
/**
* @brief Allign the block on disk to device block size.
*
- * If set in combination with @ref SQFS_BLK_FIRST_BLOCK, the output
- * file is padded to a multiple of the device block size before writing
- * the block.
- *
- * If used with @ref SQFS_BLK_LAST_BLOCK, the output file is padded
- * after writing the block.
+ * If set, the @ref sqfs_data_writer_t will add padding before the
+ * first block of the affected file and after the last block.
*/
SQFS_BLK_ALLIGN = 0x0002,
/**
- * @brief Indicates that an equeued block is the first block of a file.
+ * @brief Set by the @ref sqfs_data_writer_t on the first
+ * block of a file.
*/
SQFS_BLK_FIRST_BLOCK = 0x0800,
/**
- * @brief Indicates that an equeued block is the last block of a file.
+ * @brief Set by the @ref sqfs_data_writer_t on the last
+ * block of a file.
*/
SQFS_BLK_LAST_BLOCK = 0x1000,
/**
- * @brief Indicates that a block is a tail end of a file and the block
- * processor should take care of fragment packing and accounting.
+ * @brief Set by the @ref sqfs_data_writer_t to indicate that a block
+ * is a tail end of a file and the block.
*/
SQFS_BLK_IS_FRAGMENT = 0x2000,
/**
- * @brief Set by the block processor on fragment blocks that
+ * @brief Set by the @ref sqfs_data_writer_t on fragment blocks that
* it generates.
*/
SQFS_BLK_FRAGMENT_BLOCK = 0x4000,
/**
- * @brief Set by compressor worker if the block was actually compressed.
+ * @brief Set by @ref sqfs_data_writer_t if the block was
+ * actually compressed.
*/
SQFS_BLK_IS_COMPRESSED = 0x8000,
diff --git a/include/sqfs/data_writer.h b/include/sqfs/data_writer.h
index 37d5479..8cf24ac 100644
--- a/include/sqfs/data_writer.h
+++ b/include/sqfs/data_writer.h
@@ -31,15 +31,15 @@
/**
* @struct sqfs_data_writer_t
*
- * @brief Encapsulates a thread pool based block processor.
+ * @brief Abstracts generating of file data and fragment blocks.
*
- * The actual implementation may even be non-threaded, depending on the
- * operating system and compile configuration.
+ * This data structure provides a simple begin/append/end interface
+ * to generate file data blocks (see @ref sqfs_data_writer_begin_file,
+ * @ref sqfs_data_writer_append and @ref sqfs_data_writer_end respectively).
*
- * Either way, the instantiated object processes data blocks that can be
- * enqueued through @ref sqfs_data_writer_enqueue. The completed blocks
- * (compressed and checksumed) are dequeued in the same order and a callback
- * is called for each one.
+ * Internally it takes care of partitioning data in the correct block sizes,
+ * adding tail-ens to fragment blocks, compressing the data, deduplicating data
+ * and finally writing it to disk.
*/
/**
@@ -169,18 +169,74 @@ sqfs_data_writer_t *sqfs_data_writer_create(size_t max_block_size,
*/
SQFS_API void sqfs_data_writer_destroy(sqfs_data_writer_t *proc);
+/**
+ * @brief Start writing a file.
+ *
+ * @memberof sqfs_data_writer_t
+ *
+ * After calling this function, call @ref sqfs_data_writer_append repeatedly to
+ * add data to the file. Finally call @ref sqfs_data_writer_end_file when you
+ * are done. After writing all files, use @ref sqfs_data_writer_finish to wait
+ * until all blocks that are still in flight are done and written to disk.
+ *
+ * The specified inode pointer is kept internally and updated with the
+ * compressed block sizes and final destinations of the file and possible
+ * fragment. You need to make sure it has enough backing-store for all blocks
+ * to come. Furthermore, since there can still be blocks in-flight even after
+ * calling @ref sqfs_data_writer_end_file, the data in the inode may still
+ * change. The only point at which the data writer is guarnteed to not touch
+ * them anymore is after @ref sqfs_data_writer_finish has returned.
+ *
+ * @param proc A pointer to a data writer object.
+ * @param inode The regular file inode representing the file. The data writer
+ * internally updates it while writing blocks to disk.
+ * @param flags A combination of @ref E_SQFS_BLK_FLAGS that can be used to
+ * micro manage how the data is processed.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
SQFS_API int sqfs_data_writer_begin_file(sqfs_data_writer_t *proc,
sqfs_inode_generic_t *inode,
uint32_t flags);
+/**
+ * @brief Append data to the current file.
+ *
+ * @memberof sqfs_data_writer_t
+ *
+ * Call this after @ref sqfs_data_writer_begin_file to add data to a file.
+ *
+ * @param proc A pointer to a data writer object.
+ * @param data A pointer to a buffer to read data from.
+ * @param size How many bytes should be copied out of the given
+ * buffer and written to disk.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
SQFS_API int sqfs_data_writer_append(sqfs_data_writer_t *proc,
const void *data, size_t size);
+/**
+ * @brief Stop writing the current file and flush everything that is
+ * buffered internally.
+ *
+ * @memberof sqfs_data_writer_t
+ *
+ * The counter part to @ref sqfs_data_writer_begin_file.
+ *
+ * Even after calling this, there might still be data blocks in-flight.
+ * Use @ref sqfs_data_writer_finish when you are done writing files to force
+ * the remaining blocks to be processed and written to disk.
+ *
+ * @param proc A pointer to a data writer object.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
+ */
SQFS_API int sqfs_data_writer_end_file(sqfs_data_writer_t *proc);
/**
- * @brief Wait for the works to finish and finally flush the current
- * fragment block.
+ * @brief Wait for the in-flight data blocks to finish and finally flush the
+ * current fragment block.
*
* @memberof sqfs_data_writer_t
*