/*
* 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