diff options
author | Mark Storer <Mark.Storer@evault.com> | 2014-08-18 10:44:19 -0700 |
---|---|---|
committer | Mark Storer <Mark.Storer@evault.com> | 2014-08-18 10:44:19 -0700 |
commit | 8af4f83e86c71b91e0d246fb0bf5425e5b1ae3c2 (patch) | |
tree | 19beb15c26ba7e440d942e4ea2d2950b8484c9d2 | |
parent | 3338e25b9faeab6a9b3cd34c6f86865f4e0fa687 (diff) | |
download | liberasurecode-8af4f83e86c71b91e0d246fb0bf5425e5b1ae3c2.tar.gz |
- Cleaned up the documentation in erasurecode.h to ensure that it
follows a common format and that it accurately reflects the code.
- Cleaned up liberasurecode_instance_destroy to ensure that the return
code is correct and that it is not trying to free data that has
not been removed from the open instances.
- Updated the tests to assert that the liberasurecode_instance_destroy
method is return correctly.
-rw-r--r-- | include/erasurecode/erasurecode.h | 53 | ||||
-rw-r--r-- | src/erasurecode.c | 18 | ||||
-rw-r--r-- | test/liberasurecode_test.c | 4 |
3 files changed, 50 insertions, 25 deletions
diff --git a/include/erasurecode/erasurecode.h b/include/erasurecode/erasurecode.h index 1b26b73..da8b3c2 100644 --- a/include/erasurecode/erasurecode.h +++ b/include/erasurecode/erasurecode.h @@ -117,7 +117,7 @@ struct ec_args { * * @param num_backends - pointer to int, size of list returned * - * @returns list of EC backends implemented + * @return list of EC backends implemented */ const char ** liberasurecode_supported_backends(int *num_backends); @@ -127,7 +127,7 @@ const char ** liberasurecode_supported_backends(int *num_backends); * * @param num_checksum_types - pointer to int, size of list returned * - * @returns list of checksum types supported for fragment data + * @return list of checksum types supported for fragment data */ const char ** liberasurecode_supported_checksum_types(int *num_checksum_types); @@ -148,7 +148,7 @@ const char ** liberasurecode_supported_checksum_types(int *num_checksum_types); * null_args - arguments for the null backend * flat_xor_hd, jerasure do not require any special args * - * @returns liberasurecode instance descriptor (int > 0) + * @return liberasurecode instance descriptor (int > 0) */ int liberasurecode_instance_create(const char *backend_name, struct ec_args *args); @@ -156,7 +156,9 @@ int liberasurecode_instance_create(const char *backend_name, /** * Close a liberasurecode instance * - * @param liberasurecode descriptor to close + * @param desc - liberasurecode descriptor to close + * + * @return 0 on success, otherwise non-zero error code */ int liberasurecode_instance_destroy(int desc); @@ -195,6 +197,7 @@ int liberasurecode_encode(int desc, * fragments (char *), allocated by liberasurecode_encode * @param encoded_parity - (char **) array of m parity * fragments (char *), allocated by liberasurecode_encode + * * @return 0 in success; -error otherwise */ int liberasurecode_encode_cleanup(int desc, char **encoded_data, char **encoded_parity); @@ -229,16 +232,16 @@ int liberasurecode_decode(int desc, * * @param desc - liberasurecode descriptor/handle * from liberasurecode_instance_create() - * @param data - (char *) buffer of data decoded by - * librasurecode_decode - * @return 0 in success; -error otherwise + * @param data - (char *) buffer of data decoded by librasurecode_decode + * + * @return 0 on success; -error otherwise */ int liberasurecode_decode_cleanup(int desc, char *data); /** * Reconstruct a missing fragment from a subset of available fragments * - * @param desc - liberasurecode descriptor/handle + * @param desc - liberasurecode descriptor/handle * from liberasurecode_instance_create() * @param available_fragments - erasure encoded fragments * @param num_fragments - number of fragments being passed in @@ -256,8 +259,17 @@ int liberasurecode_reconstruct_fragment(int desc, /** * Determine which fragments are needed to reconstruct some subset - * of missing fragments. Returns a list of lists (as bitmaps) - * of fragments required to reconstruct missing indexes. + * of missing fragments. The two lists passed into the method (missing_idxs, + * and fragments_needed), must be allocated by the user. + * + * @param desc - liberasurecode descriptor/handle + * from liberasurecode_instance_create() + * @param missing_idxs - -1 terminated list of missing indexes + * @param fragements_needed - integer array of length at least k + 1, on + * successful completion, this array will be a -1 terminated list of + * required fragment indexes. + * + * @return 0 on success, non-zero on error */ int liberasurecode_fragments_needed(int desc, int *missing_idxs, int *fragments_needed); @@ -288,9 +300,10 @@ fragment_metadata * @param desc - liberasurecode descriptor/handle * from liberasurecode_instance_create() * @param fragment - fragment data pointer + * @param fragment_metadata - pointer to allocated buffer of size at least + * sizeof(struct fragment_metadata) to hold fragment metadata struct * - * @param fragment_metadata - pointer to output fragment metadata struct - * (reference passed by the user) + * @return 0 on success, non-zero on error */ int liberasurecode_get_fragment_metadata(int desc, char *fragment, fragment_metadata_t *fragment_metadata); @@ -301,10 +314,9 @@ int liberasurecode_get_fragment_metadata(int desc, * @param desc - liberasurecode descriptor/handle * from liberasurecode_instance_create() * @param fragments - fragments part of the EC stripe to verify - * @num_fragments - number of fragments part of the EC stripe + * @param num_fragments - number of fragments part of the EC stripe * - * @ returns 1 if stripe checksum verification is successful - * 0 otherwise + * @return 1 if stripe checksum verification is successful, 0 otherwise */ int liberasurecode_verify_stripe_metadata(int desc, char **fragments, int num_fragments); @@ -317,12 +329,23 @@ int liberasurecode_verify_stripe_metadata(int desc, * to be algined with the word size (w) and the last fragment also * needs to be aligned. This computes the sum of the algined fragment * sizes for a given buffer to encode. + * + * @param desc - liberasurecode descriptor/handle + * from liberasurecode_instance_create() + * @param data_len - original data length in bytes + * + * @return aligned length, or -error code on error */ int liberasurecode_get_aligned_data_size(int desc, uint64_t data_len); /** * This will return the minimum encode size, which is the minimum * buffer size that can be encoded. + * + * @param desc - liberasurecode descriptor/handle + * from liberasurecode_instance_create() + * + * @return minimum data length length, or -error code on error */ int liberasurecode_get_minimum_encode_size(int desc); diff --git a/src/erasurecode.c b/src/erasurecode.c index 2a5bd9b..9b41293 100644 --- a/src/erasurecode.c +++ b/src/erasurecode.c @@ -93,7 +93,7 @@ int next_backend_desc = 0; /** * Look up a backend instance by descriptor * - * Returns pointer to a registered liberasurecode instance + * @returns pointer to a registered liberasurecode instance * The caller must hold active_instances_rwlock */ ec_backend_t liberasurecode_backend_instance_get_by_desc(int desc) @@ -342,10 +342,12 @@ int liberasurecode_instance_create(const char *backend_name, */ int liberasurecode_instance_destroy(int desc) { - ec_backend_t instance = liberasurecode_backend_instance_get_by_desc(desc); + ec_backend_t instance = NULL; /* instance to destroy */ + int rc = 0; /* return code */ + instance = liberasurecode_backend_instance_get_by_desc(desc); if (NULL == instance) - return 0; + return EBACKENDNOTAVAIL; /* Call private exit() for the backend */ instance->common.ops->exit(instance->desc.backend_desc); @@ -354,12 +356,12 @@ int liberasurecode_instance_destroy(int desc) liberasurecode_backend_close(instance); /* Remove instace from registry */ - liberasurecode_backend_instance_unregister(instance); - - /* Cleanup */ - free(instance); + rc = liberasurecode_backend_instance_unregister(instance); + if (rc == 0) { + free(instance); + } - return 0; + return rc; } /** diff --git a/test/liberasurecode_test.c b/test/liberasurecode_test.c index cfa24bf..f82a87b 100644 --- a/test/liberasurecode_test.c +++ b/test/liberasurecode_test.c @@ -135,7 +135,7 @@ static void test_create_and_destroy_backend( return; } assert(desc > 0); - liberasurecode_instance_destroy(desc); + assert(0 == liberasurecode_instance_destroy(desc)); } static void encode_decode_test_impl(const char *backend, @@ -177,7 +177,7 @@ static void encode_decode_test_impl(const char *backend, assert(memcmp(decoded_data, orig_data, orig_data_size) == 0); if (desc) - liberasurecode_instance_destroy(desc); + assert(0 == liberasurecode_instance_destroy(desc)); free(orig_data); if (avail_frags != NULL) { |