From c2d113685e621a3074ab11827d7a440600cb7367 Mon Sep 17 00:00:00 2001 From: Andrea Mazzoleni Date: Sat, 12 Mar 2011 23:36:37 +0100 Subject: [PATCH] More comments in the source --- elem.h | 30 ++++++++++++++++++++++++++---- handle.h | 9 +++++++++ parity.h | 22 ++++++++++++++++++++-- state.h | 20 ++++++++++++++++---- 4 files changed, 71 insertions(+), 10 deletions(-) diff --git a/elem.h b/elem.h index 3a5784bf..b52c128a 100644 --- a/elem.h +++ b/elem.h @@ -81,7 +81,7 @@ struct snapraid_file { */ struct snapraid_disk { char name[PATH_MAX]; /**< Name of the disk. */ - char dir[PATH_MAX]; /**< Mount point of the disk. */ + char dir[PATH_MAX]; /**< Mount point of the disk. It always terminates with /. */ block_off_t first_free_block; /**< First free searching block. */ tommy_list filelist; /**< List of all the files. */ tommy_hashdyn fileset; /**< Hashtable by sub of all the files. */ @@ -89,31 +89,53 @@ struct snapraid_disk { }; /** - * Get the relative position of a block inside the file. + * Gets the relative position of a block inside the file. */ block_off_t block_file_pos(struct snapraid_block* block); /** - * Get the size in bytes of the block. - * If it's the last block of a file it could less than block_size. + * Gets the size in bytes of the block. + * If it's the last block of a file it could be less than block_size. */ unsigned block_file_size(struct snapraid_block* block, unsigned block_size); +/** + * Allocates a file. + */ struct snapraid_file* file_alloc(unsigned block_size, const char* sub, data_off_t size, time_t mtime); +/** + * Deallocate a file. + */ void file_free(struct snapraid_file* file); +/** + * Compares two files by path. + */ int file_compare(const void* void_arg, const void* void_data); +/** + * Computes the hash of a file path. + */ static inline tommy_uint32_t file_hash(const char* sub) { return tommy_hash_u32(0, sub, strlen(sub)); } +/** + * Allocates a disk. + */ struct snapraid_disk* disk_alloc(const char* name, const char* dir); +/** + * Deallocates a disk. + */ void disk_free(struct snapraid_disk* disk); +/** + * Gets a specific block of a disk. + * Returns 0 if the block is over the end of the disk or not used. + */ static inline struct snapraid_block* disk_block_get(struct snapraid_disk* disk, block_off_t pos) { if (pos < tommy_array_size(&disk->blockarr)) diff --git a/handle.h b/handle.h index 22c01a9d..fdb8c208 100644 --- a/handle.h +++ b/handle.h @@ -40,10 +40,19 @@ int handle_create(struct snapraid_handle* handle, struct snapraid_file* file); */ int handle_open(int ret_on_error, struct snapraid_handle* handle, struct snapraid_file* file); +/** + * Close a file. + */ void handle_close(struct snapraid_handle* handle); +/** + * Read a block from a file. + */ int handle_read(int ret_on_error, struct snapraid_handle* handle, struct snapraid_block* block, unsigned char* block_buffer, unsigned block_size); +/** + * Writes a block to a file. + */ void handle_write(struct snapraid_handle* handle, struct snapraid_block* block, unsigned char* block_buffer, unsigned block_size); #endif diff --git a/parity.h b/parity.h index b81e608f..3f05c1b9 100644 --- a/parity.h +++ b/parity.h @@ -26,17 +26,35 @@ */ block_off_t parity_resize(struct snapraid_state* state); +/** + * Creates the parity file. + */ int parity_create(const char* path, data_off_t size); +/** + * Opens an already existing parity file. + */ int parity_open(int ret_on_error, const char* path); +/** + * Flushes the parity file in the disk. + */ void parity_sync(const char* path, int f); +/** + * Closes the parity file. + */ void parity_close(const char* path, int f); -void parity_write(const char* parity_path, int parity_f, block_off_t pos, unsigned char* block_buffer, unsigned block_size); - +/** + * Read a block from the parity file. + */ int parity_read(int ret_on_error, const char* parity_path, int parity_f, block_off_t pos, unsigned char* block_buffer, unsigned block_size); +/** + * Writes a block in the parity file. + */ +void parity_write(const char* parity_path, int parity_f, block_off_t pos, unsigned char* block_buffer, unsigned block_size); + #endif diff --git a/state.h b/state.h index ac11115a..f755cef7 100644 --- a/state.h +++ b/state.h @@ -35,10 +35,19 @@ struct snapraid_state { tommy_array diskarr; /**< Disk array. */ }; +/** + * Initializes the state. + */ void state_init(struct snapraid_state* state); +/** + * Deinitializes the state. + */ void state_done(struct snapraid_state* state); +/** + * Read the configuration file. + */ void state_config(struct snapraid_state* state, const char* path, int verbose, int force); /** @@ -47,25 +56,28 @@ void state_config(struct snapraid_state* state, const char* path, int verbose, i void state_read(struct snapraid_state* state); /** - * Write the new state. + * Writes the new state. */ void state_write(struct snapraid_state* state); /** - * Update the internal state to represent the new state. + * Scans all the disks to update the state. */ void state_scan(struct snapraid_state* state); /** - * Sync. + * Syncs the parity data. */ void state_sync(struct snapraid_state* state, block_off_t blockstart); /** - * Check. + * Checks (and fixes) all the files and the parity data. */ void state_check(struct snapraid_state* state, int fix, block_off_t blockstart); +/** + * Writes the progress. + */ int state_progress(time_t* start, time_t* last, block_off_t blockpos, block_off_t blockmax, data_off_t count_block, data_off_t count_size); #endif