|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
|
|
Packit |
13e616 |
* Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
|
|
Packit |
13e616 |
* Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* This software is available to you under a choice of one of two
|
|
Packit |
13e616 |
* licenses. You may choose to be licensed under the terms of the GNU
|
|
Packit |
13e616 |
* General Public License (GPL) Version 2, available from the file
|
|
Packit |
13e616 |
* COPYING in the main directory of this source tree, or the
|
|
Packit |
13e616 |
* OpenIB.org BSD license below:
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Redistribution and use in source and binary forms, with or
|
|
Packit |
13e616 |
* without modification, are permitted provided that the following
|
|
Packit |
13e616 |
* conditions are met:
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* - Redistributions of source code must retain the above
|
|
Packit |
13e616 |
* copyright notice, this list of conditions and the following
|
|
Packit |
13e616 |
* disclaimer.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* - Redistributions in binary form must reproduce the above
|
|
Packit |
13e616 |
* copyright notice, this list of conditions and the following
|
|
Packit |
13e616 |
* disclaimer in the documentation and/or other materials
|
|
Packit |
13e616 |
* provided with the distribution.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
Packit |
13e616 |
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
Packit |
13e616 |
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
Packit |
13e616 |
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
|
|
Packit |
13e616 |
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
|
|
Packit |
13e616 |
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
Packit |
13e616 |
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
Packit |
13e616 |
* SOFTWARE.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* Abstract:
|
|
Packit |
13e616 |
* Declaration of quick map, a binary tree where the caller always provides
|
|
Packit |
13e616 |
* all necessary storage.
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
#ifndef _CL_QMAP_H_
|
|
Packit |
13e616 |
#define _CL_QMAP_H_
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
#include <complib/cl_qpool.h>
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
#ifdef __cplusplus
|
|
Packit |
13e616 |
# define BEGIN_C_DECLS extern "C" {
|
|
Packit |
13e616 |
# define END_C_DECLS }
|
|
Packit |
13e616 |
#else /* !__cplusplus */
|
|
Packit |
13e616 |
# define BEGIN_C_DECLS
|
|
Packit |
13e616 |
# define END_C_DECLS
|
|
Packit |
13e616 |
#endif /* __cplusplus */
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
BEGIN_C_DECLS
|
|
Packit |
13e616 |
/****h* Component Library/Quick Map
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* Quick Map
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* Quick map implements a binary tree that stores user provided cl_map_item_t
|
|
Packit |
13e616 |
* structures. Each item stored in a quick map has a unique 64-bit key
|
|
Packit |
13e616 |
* (duplicates are not allowed). Quick map provides the ability to
|
|
Packit |
13e616 |
* efficiently search for an item given a key.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Quick map does not allocate any memory, and can therefore not fail
|
|
Packit |
13e616 |
* any operations due to insufficient memory. Quick map can thus be useful
|
|
Packit |
13e616 |
* in minimizing the error paths in code.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Quick map is not thread safe, and users must provide serialization when
|
|
Packit |
13e616 |
* adding and removing items from the map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* The quick map functions operate on a cl_qmap_t structure which should be
|
|
Packit |
13e616 |
* treated as opaque and should be manipulated only through the provided
|
|
Packit |
13e616 |
* functions.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Structures:
|
|
Packit |
13e616 |
* cl_qmap_t, cl_map_item_t, cl_map_obj_t
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Callbacks:
|
|
Packit |
13e616 |
* cl_pfn_qmap_apply_t
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Item Manipulation:
|
|
Packit |
13e616 |
* cl_qmap_set_obj, cl_qmap_obj, cl_qmap_key
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Initialization:
|
|
Packit |
13e616 |
* cl_qmap_init
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Iteration:
|
|
Packit |
13e616 |
* cl_qmap_end, cl_qmap_head, cl_qmap_tail, cl_qmap_next, cl_qmap_prev
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Manipulation:
|
|
Packit |
13e616 |
* cl_qmap_insert, cl_qmap_get, cl_qmap_remove_item, cl_qmap_remove,
|
|
Packit |
13e616 |
* cl_qmap_remove_all, cl_qmap_merge, cl_qmap_delta, cl_qmap_get_next
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Search:
|
|
Packit |
13e616 |
* cl_qmap_apply_func
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Attributes:
|
|
Packit |
13e616 |
* cl_qmap_count, cl_is_qmap_empty,
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
/****i* Component Library: Quick Map/cl_map_color_t
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_map_color_t
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_map_color_t enumerated type is used to note the color of
|
|
Packit |
13e616 |
* nodes in a map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
typedef enum _cl_map_color {
|
|
Packit |
13e616 |
CL_MAP_RED,
|
|
Packit |
13e616 |
CL_MAP_BLACK
|
|
Packit |
13e616 |
} cl_map_color_t;
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* VALUES
|
|
Packit |
13e616 |
* CL_MAP_RED
|
|
Packit |
13e616 |
* The node in the map is red.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* CL_MAP_BLACK
|
|
Packit |
13e616 |
* The node in the map is black.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_map_item_t
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****s* Component Library: Quick Map/cl_map_item_t
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_map_item_t
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_map_item_t structure is used by maps to store objects.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* The cl_map_item_t structure should be treated as opaque and should
|
|
Packit |
13e616 |
* be manipulated only through the provided functions.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
typedef struct _cl_map_item {
|
|
Packit |
13e616 |
/* Must be first to allow casting. */
|
|
Packit |
13e616 |
cl_pool_item_t pool_item;
|
|
Packit |
13e616 |
struct _cl_map_item *p_left;
|
|
Packit |
13e616 |
struct _cl_map_item *p_right;
|
|
Packit |
13e616 |
struct _cl_map_item *p_up;
|
|
Packit |
13e616 |
cl_map_color_t color;
|
|
Packit |
13e616 |
uint64_t key;
|
|
Packit |
13e616 |
#ifdef _DEBUG_
|
|
Packit |
13e616 |
struct _cl_qmap *p_map;
|
|
Packit |
13e616 |
#endif
|
|
Packit |
13e616 |
} cl_map_item_t;
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* FIELDS
|
|
Packit |
13e616 |
* pool_item
|
|
Packit |
13e616 |
* Used to store the item in a doubly linked list, allowing more
|
|
Packit |
13e616 |
* efficient map traversal.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* p_left
|
|
Packit |
13e616 |
* Pointer to the map item that is a child to the left of the node.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* p_right
|
|
Packit |
13e616 |
* Pointer to the map item that is a child to the right of the node.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* p_up
|
|
Packit |
13e616 |
* Pointer to the map item that is the parent of the node.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* color
|
|
Packit |
13e616 |
* Indicates whether a node is red or black in the map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* key
|
|
Packit |
13e616 |
* Value that uniquely represents a node in a map. This value is
|
|
Packit |
13e616 |
* set by calling cl_qmap_insert and can be retrieved by calling
|
|
Packit |
13e616 |
* cl_qmap_key.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* None of the fields of this structure should be manipulated by users, as
|
|
Packit |
13e616 |
* they are crititcal to the proper operation of the map in which they
|
|
Packit |
13e616 |
* are stored.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* To allow storing items in either a quick list, a quick pool, or a quick
|
|
Packit |
13e616 |
* map, the map implementation guarantees that the map item can be safely
|
|
Packit |
13e616 |
* cast to a pool item used for storing an object in a quick pool, or cast
|
|
Packit |
13e616 |
* to a list item used for storing an object in a quick list. This removes
|
|
Packit |
13e616 |
* the need to embed a map item, a list item, and a pool item in objects
|
|
Packit |
13e616 |
* that need to be stored in a quick list, a quick pool, and a quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_insert, cl_qmap_key, cl_pool_item_t, cl_list_item_t
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****s* Component Library: Quick Map/cl_map_obj_t
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_map_obj_t
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_map_obj_t structure is used to store objects in maps.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* The cl_map_obj_t structure should be treated as opaque and should
|
|
Packit |
13e616 |
* be manipulated only through the provided functions.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
typedef struct _cl_map_obj {
|
|
Packit |
13e616 |
cl_map_item_t item;
|
|
Packit |
13e616 |
const void *p_object;
|
|
Packit |
13e616 |
} cl_map_obj_t;
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* FIELDS
|
|
Packit |
13e616 |
* item
|
|
Packit |
13e616 |
* Map item used by internally by the map to store an object.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* p_object
|
|
Packit |
13e616 |
* User defined context. Users should not access this field directly.
|
|
Packit |
13e616 |
* Use cl_qmap_set_obj and cl_qmap_obj to set and retrieve the value
|
|
Packit |
13e616 |
* of this field.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* None of the fields of this structure should be manipulated by users, as
|
|
Packit |
13e616 |
* they are crititcal to the proper operation of the map in which they
|
|
Packit |
13e616 |
* are stored.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Use cl_qmap_set_obj and cl_qmap_obj to set and retrieve the object
|
|
Packit |
13e616 |
* stored in a map item, respectively.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_set_obj, cl_qmap_obj, cl_map_item_t
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****s* Component Library: Quick Map/cl_qmap_t
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_t
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* Quick map structure.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* The cl_qmap_t structure should be treated as opaque and should
|
|
Packit |
13e616 |
* be manipulated only through the provided functions.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
typedef struct _cl_qmap {
|
|
Packit |
13e616 |
cl_map_item_t root;
|
|
Packit |
13e616 |
cl_map_item_t nil;
|
|
Packit |
13e616 |
cl_state_t state;
|
|
Packit |
13e616 |
size_t count;
|
|
Packit |
13e616 |
} cl_qmap_t;
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* root
|
|
Packit |
13e616 |
* Map item that serves as root of the map. The root is set up to
|
|
Packit |
13e616 |
* always have itself as parent. The left pointer is set to point
|
|
Packit |
13e616 |
* to the item at the root.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* nil
|
|
Packit |
13e616 |
* Map item that serves as terminator for all leaves, as well as
|
|
Packit |
13e616 |
* providing the list item used as quick list for storing map items
|
|
Packit |
13e616 |
* in a list for faster traversal.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* state
|
|
Packit |
13e616 |
* State of the map, used to verify that operations are permitted.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* count
|
|
Packit |
13e616 |
* Number of items in the map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****d* Component Library: Quick Map/cl_pfn_qmap_apply_t
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_pfn_qmap_apply_t
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_pfn_qmap_apply_t function type defines the prototype for
|
|
Packit |
13e616 |
* functions used to iterate items in a quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
typedef void
|
|
Packit |
13e616 |
(*cl_pfn_qmap_apply_t) (IN cl_map_item_t * const p_map_item, IN void *context);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map_item
|
|
Packit |
13e616 |
* [in] Pointer to a cl_map_item_t structure.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* context
|
|
Packit |
13e616 |
* [in] Value passed to the callback function.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* This function does not return a value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* This function type is provided as function prototype reference for the
|
|
Packit |
13e616 |
* function provided by users as a parameter to the cl_qmap_apply_func
|
|
Packit |
13e616 |
* function.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_apply_func
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_count
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_count
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_count function returns the number of items stored
|
|
Packit |
13e616 |
* in a quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
static inline uint32_t cl_qmap_count(IN const cl_qmap_t * const p_map)
|
|
Packit |
13e616 |
{
|
|
Packit |
13e616 |
CL_ASSERT(p_map);
|
|
Packit |
13e616 |
CL_ASSERT(p_map->state == CL_INITIALIZED);
|
|
Packit |
13e616 |
return ((uint32_t) p_map->count);
|
|
Packit |
13e616 |
}
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map
|
|
Packit |
13e616 |
* [in] Pointer to a cl_qmap_t structure whose item count to return.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* Returns the number of items stored in the map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_is_qmap_empty
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_is_qmap_empty
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_is_qmap_empty
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_is_qmap_empty function returns whether a quick map is empty.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
static inline boolean_t cl_is_qmap_empty(IN const cl_qmap_t * const p_map)
|
|
Packit |
13e616 |
{
|
|
Packit |
13e616 |
CL_ASSERT(p_map);
|
|
Packit |
13e616 |
CL_ASSERT(p_map->state == CL_INITIALIZED);
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
return (p_map->count == 0);
|
|
Packit |
13e616 |
}
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map
|
|
Packit |
13e616 |
* [in] Pointer to a cl_qmap_t structure to test for emptiness.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* TRUE if the quick map is empty.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* FALSE otherwise.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_count, cl_qmap_remove_all
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_set_obj
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_set_obj
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_set_obj function sets the object stored in a map object.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
static inline void
|
|
Packit |
13e616 |
cl_qmap_set_obj(IN cl_map_obj_t * const p_map_obj,
|
|
Packit |
13e616 |
IN const void *const p_object)
|
|
Packit |
13e616 |
{
|
|
Packit |
13e616 |
CL_ASSERT(p_map_obj);
|
|
Packit |
13e616 |
p_map_obj->p_object = p_object;
|
|
Packit |
13e616 |
}
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map_obj
|
|
Packit |
13e616 |
* [in] Pointer to a map object stucture whose object pointer
|
|
Packit |
13e616 |
* is to be set.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* p_object
|
|
Packit |
13e616 |
* [in] User defined context.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* This function does not return a value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_obj
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_obj
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_obj
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_obj function returns the object stored in a map object.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
static inline void *cl_qmap_obj(IN const cl_map_obj_t * const p_map_obj)
|
|
Packit |
13e616 |
{
|
|
Packit |
13e616 |
CL_ASSERT(p_map_obj);
|
|
Packit |
13e616 |
return ((void *)p_map_obj->p_object);
|
|
Packit |
13e616 |
}
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map_obj
|
|
Packit |
13e616 |
* [in] Pointer to a map object stucture whose object pointer to return.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* Returns the value of the object pointer stored in the map object.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_set_obj
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_key
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_key
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_key function retrieves the key value of a map item.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
static inline uint64_t cl_qmap_key(IN const cl_map_item_t * const p_item)
|
|
Packit |
13e616 |
{
|
|
Packit |
13e616 |
CL_ASSERT(p_item);
|
|
Packit |
13e616 |
return (p_item->key);
|
|
Packit |
13e616 |
}
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_item
|
|
Packit |
13e616 |
* [in] Pointer to a map item whose key value to return.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* Returns the 64-bit key value for the specified map item.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* The key value is set in a call to cl_qmap_insert.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_insert
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_init
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_init
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_init function initialized a quick map for use.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
void cl_qmap_init(IN cl_qmap_t * const p_map);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map
|
|
Packit |
13e616 |
* [in] Pointer to a cl_qmap_t structure to initialize.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* This function does not return a value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* Allows calling quick map manipulation functions.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_insert, cl_qmap_remove
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_end
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_end
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_end function returns the end of a quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
static inline const cl_map_item_t *cl_qmap_end(IN const cl_qmap_t * const p_map)
|
|
Packit |
13e616 |
{
|
|
Packit |
13e616 |
CL_ASSERT(p_map);
|
|
Packit |
13e616 |
CL_ASSERT(p_map->state == CL_INITIALIZED);
|
|
Packit |
13e616 |
/* Nil is the end of the map. */
|
|
Packit |
13e616 |
return (&p_map->nil);
|
|
Packit |
13e616 |
}
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map
|
|
Packit |
13e616 |
* [in] Pointer to a cl_qmap_t structure whose end to return.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* Pointer to the end of the map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* cl_qmap_end is useful for determining the validity of map items returned
|
|
Packit |
13e616 |
* by cl_qmap_head, cl_qmap_tail, cl_qmap_next, or cl_qmap_prev. If the
|
|
Packit |
13e616 |
* map item pointer returned by any of these functions compares to the end,
|
|
Packit |
13e616 |
* the end of the map was encoutered.
|
|
Packit |
13e616 |
* When using cl_qmap_head or cl_qmap_tail, this condition indicates that
|
|
Packit |
13e616 |
* the map is empty.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_head, cl_qmap_tail, cl_qmap_next, cl_qmap_prev
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_head
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_head
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_head function returns the map item with the lowest key
|
|
Packit |
13e616 |
* value stored in a quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
static inline cl_map_item_t *cl_qmap_head(IN const cl_qmap_t * const p_map)
|
|
Packit |
13e616 |
{
|
|
Packit |
13e616 |
CL_ASSERT(p_map);
|
|
Packit |
13e616 |
CL_ASSERT(p_map->state == CL_INITIALIZED);
|
|
Packit |
13e616 |
return ((cl_map_item_t *) p_map->nil.pool_item.list_item.p_next);
|
|
Packit |
13e616 |
}
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map
|
|
Packit |
13e616 |
* [in] Pointer to a cl_qmap_t structure whose item with the lowest
|
|
Packit |
13e616 |
* key is returned.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* Pointer to the map item with the lowest key in the quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Pointer to the map end if the quick map was empty.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* cl_qmap_head does not remove the item from the map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_tail, cl_qmap_next, cl_qmap_prev, cl_qmap_end,
|
|
Packit |
13e616 |
* cl_qmap_item_t
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_tail
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_tail
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_tail function returns the map item with the highest key
|
|
Packit |
13e616 |
* value stored in a quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
static inline cl_map_item_t *cl_qmap_tail(IN const cl_qmap_t * const p_map)
|
|
Packit |
13e616 |
{
|
|
Packit |
13e616 |
CL_ASSERT(p_map);
|
|
Packit |
13e616 |
CL_ASSERT(p_map->state == CL_INITIALIZED);
|
|
Packit |
13e616 |
return ((cl_map_item_t *) p_map->nil.pool_item.list_item.p_prev);
|
|
Packit |
13e616 |
}
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map
|
|
Packit |
13e616 |
* [in] Pointer to a cl_qmap_t structure whose item with the
|
|
Packit |
13e616 |
* highest key is returned.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* Pointer to the map item with the highest key in the quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Pointer to the map end if the quick map was empty.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* cl_qmap_end does not remove the item from the map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_head, cl_qmap_next, cl_qmap_prev, cl_qmap_end,
|
|
Packit |
13e616 |
* cl_qmap_item_t
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_next
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_next
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_next function returns the map item with the next higher
|
|
Packit |
13e616 |
* key value than a specified map item.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
static inline cl_map_item_t *cl_qmap_next(IN const cl_map_item_t * const p_item)
|
|
Packit |
13e616 |
{
|
|
Packit |
13e616 |
CL_ASSERT(p_item);
|
|
Packit |
13e616 |
return ((cl_map_item_t *) p_item->pool_item.list_item.p_next);
|
|
Packit |
13e616 |
}
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_item
|
|
Packit |
13e616 |
* [in] Pointer to a map item whose successor to return.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* Pointer to the map item with the next higher key value in a quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Pointer to the map end if the specified item was the last item in
|
|
Packit |
13e616 |
* the quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_head, cl_qmap_tail, cl_qmap_prev, cl_qmap_end,
|
|
Packit |
13e616 |
* cl_map_item_t
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_prev
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_prev
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_prev function returns the map item with the next lower
|
|
Packit |
13e616 |
* key value than a precified map item.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
static inline cl_map_item_t *cl_qmap_prev(IN const cl_map_item_t * const p_item)
|
|
Packit |
13e616 |
{
|
|
Packit |
13e616 |
CL_ASSERT(p_item);
|
|
Packit |
13e616 |
return ((cl_map_item_t *) p_item->pool_item.list_item.p_prev);
|
|
Packit |
13e616 |
}
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_item
|
|
Packit |
13e616 |
* [in] Pointer to a map item whose predecessor to return.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* Pointer to the map item with the next lower key value in a quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Pointer to the map end if the specifid item was the first item in
|
|
Packit |
13e616 |
* the quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_head, cl_qmap_tail, cl_qmap_next, cl_qmap_end,
|
|
Packit |
13e616 |
* cl_map_item_t
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_insert
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_insert
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_insert function inserts a map item into a quick map.
|
|
Packit |
13e616 |
* NOTE: Only if such a key does not alerady exist in the map !!!!
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
cl_map_item_t *cl_qmap_insert(IN cl_qmap_t * const p_map,
|
|
Packit |
13e616 |
IN const uint64_t key,
|
|
Packit |
13e616 |
IN cl_map_item_t * const p_item);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map
|
|
Packit |
13e616 |
* [in] Pointer to a cl_qmap_t structure into which to add the item.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* key
|
|
Packit |
13e616 |
* [in] Value to assign to the item.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* p_item
|
|
Packit |
13e616 |
* [in] Pointer to a cl_map_item_t stucture to insert into the quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* Pointer to the item in the map with the specified key. If insertion
|
|
Packit |
13e616 |
* was successful, this is the pointer to the item. If an item with the
|
|
Packit |
13e616 |
* specified key already exists in the map, the pointer to that item is
|
|
Packit |
13e616 |
* returned - but the new key is NOT inserted...
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* Insertion operations may cause the quick map to rebalance.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_remove, cl_map_item_t
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_get
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_get
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_get function returns the map item associated with a key.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
cl_map_item_t *cl_qmap_get(IN const cl_qmap_t * const p_map,
|
|
Packit |
13e616 |
IN const uint64_t key);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map
|
|
Packit |
13e616 |
* [in] Pointer to a cl_qmap_t structure from which to retrieve the
|
|
Packit |
13e616 |
* item with the specified key.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* key
|
|
Packit |
13e616 |
* [in] Key value used to search for the desired map item.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* Pointer to the map item with the desired key value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Pointer to the map end if there was no item with the desired key value
|
|
Packit |
13e616 |
* stored in the quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* cl_qmap_get does not remove the item from the quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_get_next, cl_qmap_remove
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_get_next
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_get_next
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_get_next function returns the first map item associated with a
|
|
Packit |
13e616 |
* key > the key specified.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
cl_map_item_t *cl_qmap_get_next(IN const cl_qmap_t * const p_map,
|
|
Packit |
13e616 |
IN const uint64_t key);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map
|
|
Packit |
13e616 |
* [in] Pointer to a cl_qmap_t structure from which to retrieve the
|
|
Packit |
13e616 |
* first item with a key > the specified key.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* key
|
|
Packit |
13e616 |
* [in] Key value used to search for the desired map item.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* Pointer to the first map item with a key > the desired key value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Pointer to the map end if there was no item with a key > the desired key
|
|
Packit |
13e616 |
* value stored in the quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* cl_qmap_get_next does not remove the item from the quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_get, cl_qmap_remove
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_remove_item
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_remove_item
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_remove_item function removes the specified map item
|
|
Packit |
13e616 |
* from a quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
void
|
|
Packit |
13e616 |
cl_qmap_remove_item(IN cl_qmap_t * const p_map,
|
|
Packit |
13e616 |
IN cl_map_item_t * const p_item);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map
|
|
Packit |
13e616 |
* [in] Pointer to a cl_qmap_t structure from which to
|
|
Packit |
13e616 |
* remove item.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* p_item
|
|
Packit |
13e616 |
* [in] Pointer to a map item to remove from its quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* This function does not return a value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* In a debug build, cl_qmap_remove_item asserts that the item being removed
|
|
Packit |
13e616 |
* is in the specified map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* Removes the map item pointed to by p_item from its quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_remove, cl_qmap_remove_all, cl_qmap_insert
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_remove
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_remove
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_remove function removes the map item with the specified key
|
|
Packit |
13e616 |
* from a quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
cl_map_item_t *cl_qmap_remove(IN cl_qmap_t * const p_map,
|
|
Packit |
13e616 |
IN const uint64_t key);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map
|
|
Packit |
13e616 |
* [in] Pointer to a cl_qmap_t structure from which to remove the item
|
|
Packit |
13e616 |
* with the specified key.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* key
|
|
Packit |
13e616 |
* [in] Key value used to search for the map item to remove.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* Pointer to the removed map item if it was found.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Pointer to the map end if no item with the specified key exists in the
|
|
Packit |
13e616 |
* quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_remove_item, cl_qmap_remove_all, cl_qmap_insert
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_remove_all
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_remove_all
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_remove_all function removes all items in a quick map,
|
|
Packit |
13e616 |
* leaving it empty.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
static inline void cl_qmap_remove_all(IN cl_qmap_t * const p_map)
|
|
Packit |
13e616 |
{
|
|
Packit |
13e616 |
CL_ASSERT(p_map);
|
|
Packit |
13e616 |
CL_ASSERT(p_map->state == CL_INITIALIZED);
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
p_map->root.p_left = &p_map->nil;
|
|
Packit |
13e616 |
p_map->nil.pool_item.list_item.p_next = &p_map->nil.pool_item.list_item;
|
|
Packit |
13e616 |
p_map->nil.pool_item.list_item.p_prev = &p_map->nil.pool_item.list_item;
|
|
Packit |
13e616 |
p_map->count = 0;
|
|
Packit |
13e616 |
}
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map
|
|
Packit |
13e616 |
* [in] Pointer to a cl_qmap_t structure to empty.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* This function does not return a value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_remove, cl_qmap_remove_item
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_merge
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_merge
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_merge function moves all items from one map to another,
|
|
Packit |
13e616 |
* excluding duplicates.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
void
|
|
Packit |
13e616 |
cl_qmap_merge(OUT cl_qmap_t * const p_dest_map,
|
|
Packit |
13e616 |
IN OUT cl_qmap_t * const p_src_map);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_dest_map
|
|
Packit |
13e616 |
* [out] Pointer to a cl_qmap_t structure to which items should be added.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* p_src_map
|
|
Packit |
13e616 |
* [in/out] Pointer to a cl_qmap_t structure whose items to add
|
|
Packit |
13e616 |
* to p_dest_map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* This function does not return a value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* Items are evaluated based on their keys only.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Upon return from cl_qmap_merge, the quick map referenced by p_src_map
|
|
Packit |
13e616 |
* contains all duplicate items.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_delta
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_delta
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_delta
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_delta function computes the differences between two maps.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
void
|
|
Packit |
13e616 |
cl_qmap_delta(IN OUT cl_qmap_t * const p_map1,
|
|
Packit |
13e616 |
IN OUT cl_qmap_t * const p_map2,
|
|
Packit |
13e616 |
OUT cl_qmap_t * const p_new, OUT cl_qmap_t * const p_old);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map1
|
|
Packit |
13e616 |
* [in/out] Pointer to the first of two cl_qmap_t structures whose
|
|
Packit |
13e616 |
* differences to compute.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* p_map2
|
|
Packit |
13e616 |
* [in/out] Pointer to the second of two cl_qmap_t structures whose
|
|
Packit |
13e616 |
* differences to compute.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* p_new
|
|
Packit |
13e616 |
* [out] Pointer to an empty cl_qmap_t structure that contains the
|
|
Packit |
13e616 |
* items unique to p_map2 upon return from the function.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* p_old
|
|
Packit |
13e616 |
* [out] Pointer to an empty cl_qmap_t structure that contains the
|
|
Packit |
13e616 |
* items unique to p_map1 upon return from the function.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* This function does not return a value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* Items are evaluated based on their keys. Items that exist in both
|
|
Packit |
13e616 |
* p_map1 and p_map2 remain in their respective maps. Items that
|
|
Packit |
13e616 |
* exist only p_map1 are moved to p_old. Likewise, items that exist only
|
|
Packit |
13e616 |
* in p_map2 are moved to p_new. This function can be useful in evaluating
|
|
Packit |
13e616 |
* changes between two maps.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Both maps pointed to by p_new and p_old must be empty on input. This
|
|
Packit |
13e616 |
* requirement removes the possibility of failures.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_qmap_merge
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Quick Map/cl_qmap_apply_func
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_qmap_apply_func
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_qmap_apply_func function executes a specified function
|
|
Packit |
13e616 |
* for every item stored in a quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
void
|
|
Packit |
13e616 |
cl_qmap_apply_func(IN const cl_qmap_t * const p_map,
|
|
Packit |
13e616 |
IN cl_pfn_qmap_apply_t pfn_func,
|
|
Packit |
13e616 |
IN const void *const context);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_map
|
|
Packit |
13e616 |
* [in] Pointer to a cl_qmap_t structure.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* pfn_func
|
|
Packit |
13e616 |
* [in] Function invoked for every item in the quick map.
|
|
Packit |
13e616 |
* See the cl_pfn_qmap_apply_t function type declaration for
|
|
Packit |
13e616 |
* details about the callback function.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* context
|
|
Packit |
13e616 |
* [in] Value to pass to the callback functions to provide context.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* This function does not return a value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* The function provided must not perform any map operations, as these
|
|
Packit |
13e616 |
* would corrupt the quick map.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Quick Map, cl_pfn_qmap_apply_t
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
END_C_DECLS
|
|
Packit |
13e616 |
#endif /* _CL_QMAP_H_ */
|