/*
 * Copyright (c) 2020 Red Hat, Inc.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301, USA. 
 *
 * $Id: //eng/vdo-releases/aluminum/src/c++/vdo/base/intMap.h#1 $
 */

#ifndef INT_MAP_H
#define INT_MAP_H

#include "common.h"

/**
 * IntMap associates pointers (<code>void *</code>) with integer keys
 * (<code>uint64_t</code>). <code>NULL</code> pointer values are not
 * supported.
 *
 * The map is implemented as hash table, which should provide constant-time
 * insert, query, and remove operations, although the insert may occasionally
 * grow the table, which is linear in the number of entries in the map. The
 * table will grow as needed to hold new entries, but will not shrink as
 * entries are removed.
 **/

typedef struct intMap IntMap;

/**
 * Allocate and initialize an IntMap.
 *
 * @param [in]  initialCapacity  the number of entries the map should
 *                               initially be capable of holding (zero tells
 *                               the map to use its own small default)
 * @param [in]  initialLoad      the load factor of the map, expressed as an
 *                               integer percentage (typically in the range
 *                               50 to 90, with zero telling the map to use
 *                               its own default)
 * @param [out] mapPtr           a pointer to hold the new IntMap
 *
 * @return UDS_SUCCESS or an error code
 **/
int makeIntMap(size_t         initialCapacity,
               unsigned int   initialLoad,
               IntMap       **mapPtr)
  __attribute__((warn_unused_result));

/**
 * Free an IntMap and null out the reference to it. NOTE: The map does not own
 * the pointer values stored in the map and they are not freed by this call.
 *
 * @param [in,out] mapPtr  the reference to the IntMap to free
 **/
void freeIntMap(IntMap **mapPtr);

/**
 * Get the number of entries stored in an IntMap.
 *
 * @param map  the IntMap to query
 *
 * @return the number of entries in the map
 **/
size_t intMapSize(const IntMap *map);

/**
 * Retrieve the value associated with a given key from the IntMap.
 *
 * @param map  the IntMap to query
 * @param key  the key to look up
 *
 * @return the value associated with the given key, or <code>NULL</code>
 *         if the key is not mapped to any value
 **/
void *intMapGet(IntMap *map, uint64_t key);

/**
 * Try to associate a value (a pointer) with an integer in an IntMap. If the
 * map already contains a mapping for the provided key, the old value is
 * only replaced with the specified value if update is true. In either case
 * the old value is returned. If the map does not already contain a value for
 * the specified key, the new value is added regardless of the value of update.
 *
 * @param [in]  map          the IntMap to attempt to modify
 * @param [in]  key          the key with which to associate the new value
 * @param [in]  newValue     the value to be associated with the key
 * @param [in]  update       whether to overwrite an existing value
 * @param [out] oldValuePtr  a pointer in which to store either the old value
 *                           (if the key was already mapped) or
 *                           <code>NULL</code> if the map did not contain the
 *                           key; <code>NULL</code> may be provided if the
 *                           caller does not need to know the old value
 *
 * @return UDS_SUCCESS or an error code
 **/
int intMapPut(IntMap    *map,
              uint64_t   key,
              void      *newValue,
              bool       update,
              void     **oldValuePtr)
  __attribute__((warn_unused_result));

/**
 * Remove the mapping for a given key from the IntMap.
 *
 * @param map  the IntMap from which to remove the mapping
 * @param key  the key whose mapping is to be removed
 *
 * @return the value that was associated with the key, or
 *         <code>NULL</code> if it was not mapped
 **/
void *intMapRemove(IntMap *map, uint64_t key);

#endif /* INT_MAP_H */