summaryrefslogtreecommitdiff
path: root/include/sqfs/block_processor.h
diff options
context:
space:
mode:
authorDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2019-09-09 23:11:03 +0200
committerDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2019-09-09 23:12:08 +0200
commitc17de5d4c2699c6c5b4759f009ce8cb6560d2f13 (patch)
treeca36c1af536583856360dd6e905fe7143ee5a562 /include/sqfs/block_processor.h
parent524869a644004b2b5eae9c6cdb14a20c0e877778 (diff)
Add doxygen annotations to all public headers
Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>
Diffstat (limited to 'include/sqfs/block_processor.h')
-rw-r--r--include/sqfs/block_processor.h197
1 files changed, 159 insertions, 38 deletions
diff --git a/include/sqfs/block_processor.h b/include/sqfs/block_processor.h
index 70cff09..ed38be6 100644
--- a/include/sqfs/block_processor.h
+++ b/include/sqfs/block_processor.h
@@ -22,54 +22,127 @@
#include "sqfs/predef.h"
-enum {
- /* only calculate checksum, do NOT compress the data */
+/**
+ * @file block_processor.h
+ *
+ * @brief Contains declarations for the data block processor.
+ */
+
+/**
+ * @struct sqfs_block_processor_t
+ *
+ * @brief Encapsulates a thread pool based block processor.
+ *
+ * The actual implementation may even be non-threaded, depending on the
+ * operating system and compile configuration.
+ *
+ * Either way, the instantiated object processes data blocks that can be
+ * enqueued through @ref sqfs_block_processor_enqueue. The completed blocks
+ * (compressed and checksumed) are dequeued in the same order and a callback
+ * is called for each one.
+ */
+
+/**
+ * @enum E_SQFS_BLK_FLAGS
+ *
+ * @brief Generic flags that tell the processor what to do with a block and
+ * flags that the processor sets when it is done with a block.
+ */
+typedef enum {
+ /**
+ * @brief Only calculate checksum, do NOT compress the data.
+ */
SQFS_BLK_DONT_COMPRESS = 0x0001,
- /* set by compressor worker if the block was actually compressed */
+ /**
+ * @brief Set by compressor worker if the block was actually compressed.
+ */
SQFS_BLK_IS_COMPRESSED = 0x0002,
- /* do not calculate block checksum */
+ /**
+ * @brief Do not calculate block checksum.
+ */
SQFS_BLK_DONT_CHECKSUM = 0x0004,
- /* set by compressor worker if compression failed */
+ /**
+ * @brief Set by compressor worker if compression failed.
+ */
SQFS_BLK_COMPRESS_ERROR = 0x0008,
- /* first user setable block flag */
+ /**
+ * @brief First user setable block flag.
+ */
SQFS_BLK_USER = 0x0080
-};
+} E_SQFS_BLK_FLAGS;
+/**
+ * @struct sqfs_block_t
+ *
+ * @brief Encapsulates a chunk of data to be processed by the block processor.
+ */
struct sqfs_block_t {
- /* used internally, ignored and overwritten when enqueueing blocks */
+ /**
+ * @brief Used internally, existing value is ignored and overwritten
+ * when enqueueing a block.
+ */
sqfs_block_t *next;
+
+ /**
+ * @brief Used internally, existing value is ignored and overwritten
+ * when enqueueing a block.
+ */
uint32_t sequence_number;
- /* Size of the data area */
+ /**
+ * @brief Size of the data area.
+ */
uint32_t size;
- /* checksum of the input data */
+ /**
+ * @brief Checksum of the input data.
+ */
uint32_t checksum;
- /* user settable file block index */
+ /**
+ * @brief User settable file block index.
+ *
+ * Can be used for purposes like indexing the block size table.
+ */
uint32_t index;
- /* user pointer associated with the block */
+ /**
+ * @brief Arbitary user pointer associated with the block.
+ */
void *user;
- /* user settable flag field */
+ /**
+ * @brief User settable flag field.
+ *
+ * A combination of @ref E_SQFS_BLK_FLAGS and custom, user
+ * settable flags.
+ */
uint32_t flags;
- /* raw data to be processed */
+ /**
+ * @brief Raw data to be processed.
+ */
uint8_t data[];
};
-/*
- Gets called for each processed block. May be called from a different thread
- than the one that calls enqueue, but only from one thread at a time.
- Guaranteed to be called on blocks in the order that they are submitted
- to enqueue.
-
- A non-zero return value is interpreted as fatal error.
+/**
+ * @brief Signature of a callback function that can is called for each block.
+ *
+ * Gets called for each processed block. May be called from a different thread
+ * than the one that calls enqueue or from the same thread, but only from one
+ * thread at a time.
+ *
+ * Guaranteed to be called on blocks in the order that they are submitted
+ * to enqueue.
+ *
+ * @param user The user pointer passed to @ref sqfs_block_processor_create.
+ * @param blk The finished block.
+ *
+ * @return A non-zero return value is interpreted as fatal error.
*/
typedef int (*sqfs_block_cb)(void *user, sqfs_block_t *blk);
@@ -77,6 +150,24 @@ typedef int (*sqfs_block_cb)(void *user, sqfs_block_t *blk);
extern "C" {
#endif
+/**
+ * @brief Create a block processor.
+ *
+ * @memberof sqfs_block_processor_t
+ *
+ * @param max_block_size The maximum size of a data block. Required for the
+ * internal scratch buffer used for compressing data.
+ * @param cmp A pointer to a compressor. If multiple worker threads are used,
+ * the deep copy function of the compressor is used to create
+ * several instances that don't interfere with each other.
+ * @param num_workers The number of worker threads to create.
+ * @param user An arbitrary user pointer to pass to the block callback.
+ * @param callback A function to call for each finished data block.
+ *
+ * @return A pointer to a block processor object on success, NULL on allocation
+ * failure or on failure to create the worker threads and
+ * synchronisation primitives.
+ */
SQFS_API
sqfs_block_processor_t *sqfs_block_processor_create(size_t max_block_size,
sqfs_compressor_t *cmp,
@@ -84,31 +175,61 @@ sqfs_block_processor_t *sqfs_block_processor_create(size_t max_block_size,
void *user,
sqfs_block_cb callback);
+/**
+ * @brief Destroy a block processor and free all memory used by it.
+ *
+ * @memberof sqfs_block_processor_t
+ *
+ * @param proc A pointer to a block processor object.
+ */
SQFS_API void sqfs_block_processor_destroy(sqfs_block_processor_t *proc);
-/*
- Add a block to be processed. Returns non-zero on error and prints a message
- to stderr.
-
- The function takes over ownership of the submitted block. It is freed with
- a after processing and calling the block callback.
-
- Even on failure, the workers may still be running and
- sqfs_block_processor_finish must be called before cleaning up.
-*/
+/**
+ * @brief Add a block to be processed.
+ *
+ * @memberof sqfs_block_processor_t
+ *
+ * The function takes over ownership of the submitted block. It is freed after
+ * processing and calling the block callback.
+ *
+ * @note Even on failure, the workers may still be running and you should still
+ * call @ref sqfs_block_processor_finish before cleaning up.
+ *
+ * @param proc A pointer to a block processor object.
+ * @param block A poitner to a block to enqueue.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure. Depending on
+ * the implementation used, the failure return value can actually come
+ * directly from the block callback.
+ */
SQFS_API int sqfs_block_processor_enqueue(sqfs_block_processor_t *proc,
sqfs_block_t *block);
-/*
- Wait for the compressor workers to finish. Returns zero on success, non-zero
- if an internal error occoured or one of the block callbacks returned a
- non-zero value.
+/**
+ * @brief Wait for the workers to finish all in-flight data blocks.
+ *
+ * @memberof sqfs_block_processor_t
+ *
+ * @param proc A pointer to a block processor object.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure. The failure
+ * return value can either be an error encountered during enqueueing,
+ * processing or a failure return status from the block callback.
*/
SQFS_API int sqfs_block_processor_finish(sqfs_block_processor_t *proc);
-/*
- Convenience function to process a data block. Returns 0 on success,
- prints to stderr on failure.
+/**
+ * @brief Convenience function to process a data block.
+ *
+ * This function actually contains the implementation of what each worker in
+ * the block processor actually does to the data blocks.
+ *
+ * @param block A pointer to a data block.
+ * @param cmp A pointer to a compressor to use.
+ * @param scratch A pointer to a scratch buffer to user for compressing.
+ * @param scratch_size The available size in the scratch buffer.
+ *
+ * @return Zero on success, an @ref E_SQFS_ERROR value on failure.
*/
SQFS_API int sqfs_block_process(sqfs_block_t *block, sqfs_compressor_t *cmp,
uint8_t *scratch, size_t scratch_size);