From 936d1e106ae1bfb5bc3694e1ed0d4670fd0bfdaa Mon Sep 17 00:00:00 2001 From: Shane Snyder Date: Fri, 17 Jun 2016 13:27:31 -0500 Subject: [PATCH] cleanup comments in darshan-common --- darshan-runtime/darshan-common.h | 81 ++++++++++++++++++---------- darshan-runtime/lib/darshan-common.c | 36 ++++++++----- 2 files changed, 78 insertions(+), 39 deletions(-) diff --git a/darshan-runtime/darshan-common.h b/darshan-runtime/darshan-common.h index e7b8d92..6cf62a1 100644 --- a/darshan-runtime/darshan-common.h +++ b/darshan-runtime/darshan-common.h @@ -76,17 +76,17 @@ * base of the value counters (i.e., the first of 4 contiguous common value * counters) and __cnt_p is a pointer to the base of the count counters (i.e. * the first of 4 contiguous common count counters). It is assumed your counters - * are stored as int64_t types. __online_flag is set if the common val counters are - * updated during runtime (as opposed to being updated once at darshan shutdown time). + * are stored as int64_t types. __add_flag is set if the given count should be + * added to the common access counter, rather than just incrementing it. */ -#define DARSHAN_COMMON_VAL_COUNTER_INC(__val_p, __cnt_p, __value, __count, __online_flag) do {\ +#define DARSHAN_COMMON_VAL_COUNTER_INC(__val_p, __cnt_p, __value, __count, __add_flag) do {\ int i; \ int inc_count, total_count; \ int64_t tmp_val[4] = {0}; \ int64_t tmp_cnt[4] = {0}; \ int tmp_ndx = 0; \ if(__value == 0) break; \ - if(__online_flag) \ + if(__add_flag) \ inc_count = 1; \ else \ inc_count = __count; \ @@ -127,10 +127,7 @@ memcpy(__cnt_p, tmp_cnt, 4*sizeof(int64_t)); \ } while(0) -/* maximum number of common values that darshan will track per file at - * runtime; at shutdown time these will be reduced to the 4 most - * frequently occuring ones - */ +/* maximum number of common values that darshan will track per file at runtime */ #define DARSHAN_COMMON_VAL_MAX_RUNTIME_COUNT 32 struct darshan_common_val_counter { @@ -157,26 +154,63 @@ struct darshan_variance_dt * darshan-common functions for darshan modules * ***********************************************/ +/* darshan_lookup_record_ref() + * + * Lookup a record reference pointer using the given 'handle'. + * 'handle_sz' is the size of the handle structure, and 'hash_head' + * is the pointer to the hash table to search. + * If the handle is found, the corresponding record reference pointer + * is returned, otherwise NULL is returned. + */ void *darshan_lookup_record_ref( void *hash_head, void *handle, size_t handle_sz); +/* darshan_add_record_ref() + * + * Add the given record reference pointer, 'rec_ref_p' to the hash + * table whose address is stored in the 'hash_head_p' pointer. The + * hash is generated from the given 'handle', with size 'handle_sz'. + * If the record reference is successfully added, 1 is returned, + * otherwise, 0 is returned. + */ int darshan_add_record_ref( - void **hash_head, + void **hash_head_p, void *handle, size_t handle_sz, void *rec_ref_p); +/* darshan_delete_record_ref() + * + * Delete the record reference for the given 'handle', with size + * 'handle_sz', from the hash table whose address is stored in + * the 'hash_head_p' pointer. + * On success deletion, the corresponding record reference pointer + * is returned, otherwise NULL is returned. + */ void *darshan_delete_record_ref( - void **hash_head, + void **hash_head_p, void *handle, size_t handle_sz); +/* darshan_clear_record_refs() + * + * Clear all record references from the hash table stored in the + * 'hash_head_p' pointer. If 'free_flag' is set, the corresponding + * record_reference_pointer is also freed. + */ void darshan_clear_record_refs( - void **hash_head, + void **hash_head_p, int free_flag); +/* darshan_iter_record_ref() + * + * Iterate each record reference stored in the hash table pointed + * to by 'hash_head' and perform the given action 'iter_action'. + * The action function takes a single pointer which points to the + * corresponding record reference pointer. + */ void darshan_iter_record_refs( void *hash_head, void (*iter_action)(void *)); @@ -191,6 +225,15 @@ void darshan_iter_record_refs( char* darshan_clean_file_path( const char *path); +/* darshan_record_sort() + * + * Sort the records in 'rec_buf' by descending rank to get all + * shared records in a contiguous region at the end of the buffer. + * Records are secondarily sorted by ascending record identifiers. + * 'rec_count' is the number of records in the buffer, and 'rec_size' + * is the size of the record structure. + * NOTE: this function only works on fixed-length records. + */ void darshan_record_sort( void *rec_buf, int rec_count, @@ -218,22 +261,6 @@ void darshan_common_val_counter( int64_t *val_p, int64_t *cnt_p); -/* darshan_walk_common_vals() - * - * Walks the tree of common value counters and determines the 4 most - * frequently occuring values, storing the common values in the - * appropriate counter fields of the given record. 'common_val_root' - * is the root of the tree which stores the common value info, 'val_p' - * is a pointer to the base counter (i.e., the first) of the common - * values (which are assumed to be 4 total and contiguous in memory), - * and 'cnt_p' is a pointer to the base counter of the common counts - * (which are again expected to be contiguous in memory). - */ -void darshan_walk_common_vals( - void *common_val_root, - int64_t *val_p, - int64_t *cnt_p); - /* darshan_variance_reduce() * * MPI reduction operation to calculate variances on counters in diff --git a/darshan-runtime/lib/darshan-common.c b/darshan-runtime/lib/darshan-common.c index a13eaf4..6b9e9da 100644 --- a/darshan-runtime/lib/darshan-common.c +++ b/darshan-runtime/lib/darshan-common.c @@ -19,7 +19,7 @@ #include "darshan.h" - +/* track opaque record referencre using a hash link */ struct darshan_record_ref_tracker { void *rec_ref_p; @@ -32,6 +32,7 @@ void *darshan_lookup_record_ref(void *hash_head, void *handle, size_t handle_sz) struct darshan_record_ref_tracker *ref_tracker_head = (struct darshan_record_ref_tracker *)hash_head; + /* search the hash table for the given handle */ HASH_FIND(hlink, ref_tracker_head, handle, handle_sz, ref_tracker); if(ref_tracker) return(ref_tracker->rec_ref_p); @@ -39,52 +40,57 @@ void *darshan_lookup_record_ref(void *hash_head, void *handle, size_t handle_sz) return(NULL); } -int darshan_add_record_ref(void **hash_head, void *handle, size_t handle_sz, +int darshan_add_record_ref(void **hash_head_p, void *handle, size_t handle_sz, void *rec_ref_p) { struct darshan_record_ref_tracker *ref_tracker; struct darshan_record_ref_tracker *ref_tracker_head = - *(struct darshan_record_ref_tracker **)hash_head; + *(struct darshan_record_ref_tracker **)hash_head_p; void *handle_p; + /* allocate a reference tracker, with room to store the handle at the end */ ref_tracker = malloc(sizeof(*ref_tracker) + handle_sz); if(!ref_tracker) return(0); memset(ref_tracker, 0, sizeof(*ref_tracker) + handle_sz); + /* initialize the reference tracker and add it to the hash table */ ref_tracker->rec_ref_p = rec_ref_p; handle_p = (char *)ref_tracker + sizeof(*ref_tracker); memcpy(handle_p, handle, handle_sz); HASH_ADD_KEYPTR(hlink, ref_tracker_head, handle_p, handle_sz, ref_tracker); - *hash_head = ref_tracker_head; + *hash_head_p = ref_tracker_head; return(1); } -void *darshan_delete_record_ref(void **hash_head, void *handle, size_t handle_sz) +void *darshan_delete_record_ref(void **hash_head_p, void *handle, size_t handle_sz) { struct darshan_record_ref_tracker *ref_tracker; struct darshan_record_ref_tracker *ref_tracker_head = - *(struct darshan_record_ref_tracker **)hash_head; + *(struct darshan_record_ref_tracker **)hash_head_p; void *rec_ref_p; + /* find the reference tracker for this handle */ HASH_FIND(hlink, ref_tracker_head, handle, handle_sz, ref_tracker); if(!ref_tracker) return(NULL); + /* if found, delete from hash table and return the record reference pointer */ HASH_DELETE(hlink, ref_tracker_head, ref_tracker); - *hash_head = ref_tracker_head; + *hash_head_p = ref_tracker_head; rec_ref_p = ref_tracker->rec_ref_p; free(ref_tracker); return(rec_ref_p); } -void darshan_clear_record_refs(void **hash_head, int free_flag) +void darshan_clear_record_refs(void **hash_head_p, int free_flag) { struct darshan_record_ref_tracker *ref_tracker, *tmp; struct darshan_record_ref_tracker *ref_tracker_head = - *(struct darshan_record_ref_tracker **)hash_head; + *(struct darshan_record_ref_tracker **)hash_head_p; + /* iterate the hash table and remove/free all reference trackers */ HASH_ITER(hlink, ref_tracker_head, ref_tracker, tmp) { HASH_DELETE(hlink, ref_tracker_head, ref_tracker); @@ -92,7 +98,7 @@ void darshan_clear_record_refs(void **hash_head, int free_flag) free(ref_tracker->rec_ref_p); free(ref_tracker); } - *hash_head = ref_tracker_head; + *hash_head_p = ref_tracker_head; return; } @@ -103,6 +109,9 @@ void darshan_iter_record_refs(void *hash_head, void (*iter_action)(void *)) struct darshan_record_ref_tracker *ref_tracker_head = (struct darshan_record_ref_tracker *)hash_head; + /* iterate the hash table, performing the given action for each reference + * tracker's corresponding record reference pointer + */ HASH_ITER(hlink, ref_tracker_head, ref_tracker, tmp) { iter_action(ref_tracker->rec_ref_p); @@ -168,8 +177,11 @@ char* darshan_clean_file_path(const char* path) return(newpath); } -/* compare function for sorting file records by descending rank first, then - * by ascending record identifiers (which are just unsigned integers) +/* compare function for sorting file records according to their + * darshan_base_record structure. Records are sorted first by + * descending rank (to get all shared records, with rank set to -1, in + * a contiguous region at the end of the record buffer) then + * by ascending record identifiers (which are just unsigned integers). */ static int darshan_base_record_compare(const void* a_p, const void* b_p) { -- 2.26.2