/*
 * 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/hashZone.h#1 $
 */

#ifndef HASH_ZONE_H
#define HASH_ZONE_H

#include "uds.h"

#include "statistics.h"
#include "types.h"

/**
 * Create a hash zone.
 *
 * @param [in]  vdo         The VDO to which the zone will belong
 * @param [in]  zoneNumber  The number of the zone to create
 * @param [out] zonePtr     A pointer to hold the new HashZone
 *
 * @return VDO_SUCCESS or an error code
 **/
int makeHashZone(VDO *vdo, ZoneCount zoneNumber, HashZone **zonePtr)
  __attribute__((warn_unused_result));

/**
 * Free a hash zone and null out the reference to it.
 *
 * @param zonePtr  A pointer to the zone to free
 **/
void freeHashZone(HashZone **zonePtr);

/**
 * Get the zone number of a hash zone.
 *
 * @param zone  The zone
 *
 * @return The number of the zone
 **/
ZoneCount getHashZoneNumber(const HashZone *zone)
  __attribute__((warn_unused_result));

/**
 * Get the ID of a hash zone's thread.
 *
 * @param zone  The zone
 *
 * @return The zone's thread ID
 **/
ThreadID getHashZoneThreadID(const HashZone *zone)
  __attribute__((warn_unused_result));

/**
 * Get the statistics for this hash zone.
 *
 * @param zone  The hash zone to query
 *
 * @return A copy of the current statistics for the hash zone
 **/
HashLockStatistics getHashZoneStatistics(const HashZone *zone)
  __attribute__((warn_unused_result));

/**
 * Get the lock for the hash (chunk name) of the data in a DataVIO, or if one
 * does not exist (or if we are explicitly rolling over), initialize a new
 * lock for the hash and register it in the zone. This must only be called in
 * the correct thread for the zone.
 *
 * @param [in]  zone         The zone responsible for the hash
 * @param [in]  hash         The hash to lock
 * @param [in]  replaceLock  If non-NULL, the lock already registered for the
 *                           hash which should be replaced by the new lock
 * @param [out] lockPtr      A pointer to receive the hash lock
 *
 * @return VDO_SUCCESS or an error code
 **/
int acquireHashLockFromZone(HashZone            *zone,
                            const UdsChunkName  *hash,
                            HashLock            *replaceLock,
                            HashLock           **lockPtr)
  __attribute__((warn_unused_result));

/**
 * Return a hash lock to the zone it was borrowed from, remove it from the
 * zone's lock map, returning it to the pool, and nulling out the reference to
 * it. This must only be called when the lock has been completely released,
 * and only in the correct thread for the zone.
 *
 * @param [in]     zone     The zone from which the lock was borrowed
 * @param [in,out] lockPtr  The lock that is no longer in use
 **/
void returnHashLockToZone(HashZone *zone, HashLock **lockPtr);

/**
 * Increment the valid advice count in the hash zone statistics.
 * Must only be called from the hash zone thread.
 *
 * @param zone  The hash zone of the lock that received valid advice
 **/
void bumpHashZoneValidAdviceCount(HashZone *zone);

/**
 * Increment the stale advice count in the hash zone statistics.
 * Must only be called from the hash zone thread.
 *
 * @param zone  The hash zone of the lock that received stale advice
 **/
void bumpHashZoneStaleAdviceCount(HashZone *zone);

/**
 * Increment the concurrent dedupe count in the hash zone statistics.
 * Must only be called from the hash zone thread.
 *
 * @param zone  The hash zone of the lock that matched a new DataVIO
 **/
void bumpHashZoneDataMatchCount(HashZone *zone);

/**
 * Increment the concurrent hash collision count in the hash zone statistics.
 * Must only be called from the hash zone thread.
 *
 * @param zone  The hash zone of the lock that rejected a colliding DataVIO
 **/
void bumpHashZoneCollisionCount(HashZone *zone);

/**
 * Dump information about a hash zone to the log for debugging.
 *
 * @param zone   The zone to dump
 **/
void dumpHashZone(const HashZone *zone);

#endif // HASH_ZONE_H