From: Stan Smith Date: Fri, 21 May 2010 19:14:26 +0000 (+0000) Subject: [INC] complib; companion to commit #2799 - add: cl_fmap_match() & cl_fmap_get_next... X-Git-Url: https://openfabrics.org/gitweb/?a=commitdiff_plain;h=46664a565eb2e52533d6346eac9c1a38e17dd0e4;p=~shefty%2Frdma-win.git [INC] complib; companion to commit #2799 - add: cl_fmap_match() & cl_fmap_get_next() for opensm 3.3.5. git-svn-id: svn://openib.tc.cornell.edu/gen1@2801 ad392aa1-c5ef-ae45-8dd8-e69d62a5ef86 --- diff --git a/trunk/inc/complib/cl_fleximap.h b/trunk/inc/complib/cl_fleximap.h index 30f72bf3..ff3dab54 100644 --- a/trunk/inc/complib/cl_fleximap.h +++ b/trunk/inc/complib/cl_fleximap.h @@ -31,23 +31,26 @@ * $Id$ */ - /* * Abstract: * Declaration of flexi map, a binary tree where the caller always provides * all necessary storage. - * - * Environment: - * All */ - #ifndef _CL_FLEXIMAP_H_ #define _CL_FLEXIMAP_H_ - #include +#ifdef __cplusplus +# define BEGIN_C_DECLS extern "C" { +# define END_C_DECLS } +#else /* !__cplusplus */ +# define BEGIN_C_DECLS +# define END_C_DECLS +#endif /* __cplusplus */ + +BEGIN_C_DECLS /****h* Component Library/Flexi Map * NAME @@ -55,11 +58,12 @@ * * DESCRIPTION * Flexi map implements a binary tree that stores user provided cl_fmap_item_t -* structures. Each item stored in a flexi map has a unique user defined key -* (duplicates are not allowed). Flexi map provides the ability to -* efficiently search for an item given a key. Flexi map allows user defined -* keys of any size. Storage for keys and a comparisson function are provided -* by users to allow flexi map to store items with arbitrary key values. +* structures. Each item stored in a flexi map has a unique user defined +* key (duplicates are not allowed). Flexi map provides the ability to +* efficiently search for an item given a key. Flexi map allows user +* defined keys of any size. Storage for keys and a comparison function +* are provided by users to allow flexi map to store items with arbitrary +* key values. * * Flexi map does not allocate any memory, and can therefore not fail * any operations due to insufficient memory. Flexi map can thus be useful @@ -90,7 +94,7 @@ * * Manipulation: * cl_fmap_insert, cl_fmap_get, cl_fmap_remove_item, cl_fmap_remove, -* cl_fmap_remove_all, cl_fmap_merge, cl_fmap_delta +* cl_fmap_remove_all, cl_fmap_merge, cl_fmap_delta, cl_fmap_get_next * * Search: * cl_fmap_apply_func @@ -99,7 +103,6 @@ * cl_fmap_count, cl_is_fmap_empty, *********/ - /****s* Component Library: Flexi Map/cl_fmap_item_t * NAME * cl_fmap_item_t @@ -171,7 +174,6 @@ typedef struct _cl_fmap_item * Flexi Map, cl_fmap_insert, cl_fmap_key, cl_pool_item_t, cl_list_item_t *********/ - /****d* Component Library: Flexi Map/cl_pfn_fmap_cmp_t * NAME * cl_pfn_fmap_cmp_t @@ -196,8 +198,8 @@ typedef int * * RETURN VALUE * Returns 0 if the keys match. -* Returns less than 0 if p_key1 is less than p_key2. -* Returns greater than 0 if p_key1 is greater than p_key2. +* Returns less than 0 if *p_key1 is less than *p_key2. +* Returns greater than 0 if *p_key1 is greater than *p_key2. * * NOTES * This function type is provided as function prototype reference for the @@ -207,7 +209,6 @@ typedef int * Flexi Map, cl_fmap_init *********/ - /****s* Component Library: Flexi Map/cl_fmap_t * NAME * cl_fmap_t @@ -255,7 +256,6 @@ typedef struct _cl_fmap * Flexi Map, cl_pfn_fmap_cmp_t *********/ - /****d* Component Library: Flexi Map/cl_pfn_fmap_apply_t * NAME * cl_pfn_fmap_apply_t @@ -290,12 +290,6 @@ typedef void * Flexi Map, cl_fmap_apply_func *********/ - -#ifdef __cplusplus -extern "C" { -#endif - - /****f* Component Library: Flexi Map/cl_fmap_count * NAME * cl_fmap_count @@ -654,6 +648,43 @@ cl_fmap_insert( * Flexi Map, cl_fmap_remove, cl_fmap_item_t *********/ +/****f* Component Library: Flexi Map/cl_fmap_match +* NAME +* cl_fmap_match +* +* DESCRIPTION +* The cl_fmap_match function returns the map item matching a key. +* +* SYNOPSIS +*/ +CL_EXPORT cl_fmap_item_t* CL_API +cl_fmap_match( + IN const cl_fmap_t * const p_map, + IN const void *const p_key, + IN cl_pfn_fmap_cmp_t pfn_compare ); +/* +* PARAMETERS +* p_map +* [in] Pointer to a cl_fmap_t structure from which to retrieve the +* item with the specified key. +* +* p_key +* [in] Pointer to a key value used to search for the desired map item. +* +* pfn_compare +* [in] Pointer to a compare function to invoke to compare the +* keys of items in the map. Passing NULL here makes such call +* to be equivalent to using cl_fmap_get(). +* +* RETURN VALUES +* Pointer to the map item matching the desired key value. +* +* Pointer to the map end if there was no item matching the desired key +* value stored in the flexi map. +* +* SEE ALSO +* Flexi Map, cl_fmap_remove, cl_fmap_get +*********/ /****f* Component Library: Flexi Map/cl_fmap_get * NAME @@ -687,9 +718,44 @@ cl_fmap_get( * cl_fmap_get does not remove the item from the flexi map. * * SEE ALSO -* Flexi Map, cl_fmap_remove +* Flexi Map, cl_fmap_remove, cl_fmap_get_next *********/ +/****f* Component Library: Flexi Map/cl_fmap_get_next +* NAME +* cl_fmap_get_next +* +* DESCRIPTION +* The cl_fmap_get_next function returns the first map item associated with a +* key > the key specified. +* +* SYNOPSIS +*/ +CL_EXPORT cl_fmap_item_t* CL_API +cl_fmap_get_next( + IN const cl_fmap_t * const p_map, + IN const void *const p_key ); +/* +* PARAMETERS +* p_map +* [in] Pointer to a cl_fmap_t structure from which to retrieve the +* item with the specified key. +* +* p_key +* [in] Pointer to a key value used to search for the desired map item. +* +* RETURN VALUES +* Pointer to the first map item with a key > the desired key value. +* +* Pointer to the map end if there was no item with a key > the desired key +* value stored in the flexi map. +* +* NOTES +* cl_fmap_get_next does not remove the item from the flexi map. +* +* SEE ALSO +* Flexi Map, cl_fmap_remove, cl_fmap_get +*********/ /****f* Component Library: Flexi Map/cl_fmap_remove_item * NAME @@ -871,7 +937,7 @@ cl_fmap_delta( * Items are evaluated based on their keys. Items that exist in both * p_map1 and p_map2 remain in their respective maps. Items that * exist only p_map1 are moved to p_old. Likewise, items that exist only -* in p_map2 are moved to p_new. This function can be usefull in evaluating +* in p_map2 are moved to p_new. This function can be useful in evaluating * changes between two maps. * * Both maps pointed to by p_new and p_old must be empty on input. This @@ -921,9 +987,6 @@ cl_fmap_apply_func( * Flexi Map, cl_pfn_fmap_apply_t *********/ -#ifdef __cplusplus -} -#endif - +END_C_DECLS #endif /* _CL_FLEXIMAP_H_ */