diff options
Diffstat (limited to 'include/sqfs/data_writer.h')
| -rw-r--r-- | include/sqfs/data_writer.h | 310 |
1 files changed, 0 insertions, 310 deletions
diff --git a/include/sqfs/data_writer.h b/include/sqfs/data_writer.h deleted file mode 100644 index 7b6ee0f..0000000 --- a/include/sqfs/data_writer.h +++ /dev/null @@ -1,310 +0,0 @@ -/* SPDX-License-Identifier: LGPL-3.0-or-later */ -/* - * data_writer.h - This file is part of libsquashfs - * - * Copyright (C) 2019 David Oberhollenzer <goliath@infraroot.at> - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License as published - * by the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program. If not, see <https://www.gnu.org/licenses/>. - */ -#ifndef SFQS_DATA_WRITER_H -#define SFQS_DATA_WRITER_H - -#include "sqfs/predef.h" - -/** - * @file data_writer.h - * - * @brief Contains declarations for the data block processor. - */ - -/** - * @struct sqfs_data_writer_t - * - * @brief Abstracts generating of file data and fragment blocks. - * - * 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). - * - * 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. - */ - -/** - * @struct sqfs_block_hooks_t - * - * @brief A set of hooks for tapping into the data writer. - * - * This structure can be registered with an @ref sqfs_data_writer_t and - * contains function pointers that will be called during various stages - * when writing data to disk. - * - * The callbacks can not only be used for accounting but may also write extra - * data to the output file or make modifications to the blocks before they are - * writtien. - * - * The callbacks can be individually set to NULL to disable them. - */ -struct sqfs_block_hooks_t { - /** - * @brief Set this to the size of the struct. - * - * This is required for future expandabillity while maintaining ABI - * compatibillity. At the current time, the implementation of - * @ref sqfs_data_writer_set_hooks rejects any hook struct where this - * isn't the exact size. If new hooks are added in the future, the - * struct grows and the future implementation can tell by the size - * whether the application uses the new version or the old one. - */ - size_t size; - - /** - * @brief Gets called before writing a block to disk. - * - * If this is not NULL, it gets called before a block is written to - * disk. If the block has the @ref SQFS_BLK_ALIGN flag set, the - * function is called before padding the file. - * - * The function may modify the block itself or write data to the file. - * which is taken into account when padding the file. - * - * @param user A user pointer. - * @param block The block that is about to be written. - * @param file The file that the block will be written to. - */ - void (*pre_block_write)(void *user, sqfs_block_t *block, - sqfs_file_t *file); - - /** - * @brief Gets called after writing a block to disk. - * - * If this is not NULL, it gets called after a block is written to - * disk. If the block has the @ref SQFS_BLK_ALIGN flag set, the - * function is called before padding the file. - * - * Modifying the block is rather pointless, but the function may - * write data to the file which is taken into account when padding - * the file. - * - * @param user A user pointer. - * @param block The block that is about to be written. - * @param file The file that the block was written to. - */ - void (*post_block_write)(void *user, const sqfs_block_t *block, - sqfs_file_t *file); - - /** - * @brief Gets called before storing a fragment in a fragment block. - * - * The function can modify the block before it is stored. - * - * @param user A user pointer. - * @param block The data chunk that is about to be merged into the - * fragment block. - */ - void (*pre_fragment_store)(void *user, sqfs_block_t *block); - - /** - * @brief Gets called if block deduplication managed to get - * rid of the data blocks of a file. - * - * @param user A user pointer. - * @param count The number of blocks that have been erased. - * @param bytes The number of bytes that have been erased. Includes - * potential padding before and after the end. - */ - void (*notify_blocks_erased)(void *user, size_t count, - sqfs_u64 bytes); - - /** - * @brief Gets called before throwing away a fragment that turned out - * to be a duplicate. - * - * @param user A user pointer. - * @param block The data chunk that is about to be merged into the - * fragment block. - */ - void (*notify_fragment_discard)(void *user, const sqfs_block_t *block); - - /** - * @brief Gets called before writing a block of padding bytes to disk. - * - * @param user A user pointer. - * @param block The padding bytes that are about to be written. - * @param count The number of padding bytes in the block. - */ - void (*prepare_padding)(void *user, sqfs_u8 *block, size_t count); -}; - -#ifdef __cplusplus -extern "C" { -#endif - -/** - * @brief Create a data block writer. - * - * @memberof sqfs_data_writer_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 max_backlog The maximum number of blocks currently in flight. When - * trying to add more, enqueueing blocks until the in-flight - * block count drops below the threshold. - * @param devblksz File can optionally be allgined to device block size. This - * specifies the desired alignment. - * @param file The output file to write the finished blocks to. - * - * @return A pointer to a data writer object on success, NULL on allocation - * failure or on failure to create and initialize the worker threads. - */ -SQFS_API -sqfs_data_writer_t *sqfs_data_writer_create(size_t max_block_size, - sqfs_compressor_t *cmp, - unsigned int num_workers, - size_t max_backlog, - size_t devblksz, - sqfs_file_t *file); - -/** - * @brief Destroy a data writer and free all memory used by it. - * - * @memberof sqfs_data_writer_t - * - * @param proc A pointer to a data writer object. - */ -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, - sqfs_u32 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 in-flight data blocks to finish and finally flush the - * current fragment block. - * - * @memberof sqfs_data_writer_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 writing to disk. - */ -SQFS_API int sqfs_data_writer_finish(sqfs_data_writer_t *proc); - -/** - * @brief Write the completed fragment table to disk. - * - * @memberof sqfs_data_writer_t - * - * Call this after producing the inode and directory table to generate - * the fragment table for the squashfs image. - * - * @param proc A pointer to a data writer object. - * @param super A pointer to a super block to write information about the - * fragment table to. - * - * @return Zero on success, an @ref E_SQFS_ERROR value on failure. - */ -SQFS_API -int sqfs_data_writer_write_fragment_table(sqfs_data_writer_t *proc, - sqfs_super_t *super); - -/** - * @brief Register a set of hooks to be invoked when writing blocks to disk. - * - * @memberof sqfs_data_writer_t - * - * @param proc A pointer to a data writer object. - * @param user_ptr A user pointer to pass to the callbacks. - * @param hooks A structure containing the hooks. - * - * @return Zero on success, @ref SQFS_ERROR_UNSUPPORTED if the size field of - * the hooks doesn't match any size knwon to the library. - */ -SQFS_API -int sqfs_data_writer_set_hooks(sqfs_data_writer_t *proc, void *user_ptr, - const sqfs_block_hooks_t *hooks); - -#ifdef __cplusplus -} -#endif - -#endif /* SFQS_DATA_WRITER_H */ |