/*

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

 */

#ifndef PHYSICAL_ZONE_H

#define PHYSICAL_ZONE_H

#include "pbnLock.h"

#include "types.h"

/**

 * Create a physical 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 PhysicalZone

 *

 * @return VDO_SUCCESS or an error code

 **/

int makePhysicalZone(VDO *vdo, ZoneCount zoneNumber, PhysicalZone **zonePtr)

  __attribute__((warn_unused_result));

/**

 * Free a physical zone and null out the reference to it.

 *

 * @param zonePtr  A pointer to the zone to free

 **/

void freePhysicalZone(PhysicalZone **zonePtr);

/**

 * Get the zone number of a physical zone.

 *

 * @param zone  The zone

 *

 * @return The number of the zone

 **/

ZoneCount getPhysicalZoneNumber(const PhysicalZone *zone)

  __attribute__((warn_unused_result));

/**

 * Get the ID of a physical zone's thread.

 *

 * @param zone  The zone

 *

 * @return The zone's thread ID

 **/

ThreadID getPhysicalZoneThreadID(const PhysicalZone *zone)

  __attribute__((warn_unused_result));

/**

 * Get the block allocator from a physical zone.

 *

 * @param zone  The zone

 *

 * @return The zone's allocator

 **/

BlockAllocator *getBlockAllocator(const PhysicalZone *zone)

  __attribute__((warn_unused_result));

/**

 * Get the lock on a PBN if one exists.

 *

 * @param zone  The physical zone responsible for the PBN

 * @param pbn   The physical block number whose lock is desired

 *

 * @return The lock or NULL if the PBN is not locked

 **/

PBNLock *getPBNLock(PhysicalZone *zone, PhysicalBlockNumber pbn)

  __attribute__((warn_unused_result));

/**

 * Attempt to lock a physical block in the zone responsible for it. If the PBN

 * is already locked, the existing lock will be returned. Otherwise, a new

 * lock instance will be borrowed from the pool, initialized, and returned.

 * The lock owner will be NULL for a new lock acquired by the caller, who is

 * responsible for setting that field promptly. The lock owner will be

 * non-NULL when there is already an existing lock on the PBN.

 *

 * @param [in]  zone     The physical zone responsible for the PBN

 * @param [in]  pbn      The physical block number to lock

 * @param [in]  type     The type with which to initialize a new lock

 * @param [out] lockPtr  A pointer to receive the lock, existing or new

 *

 * @return VDO_SUCCESS or an error

 **/

int attemptPBNLock(PhysicalZone         *zone,

                   PhysicalBlockNumber   pbn,

                   PBNLockType           type,

                   PBNLock             **lockPtr)

  __attribute__((warn_unused_result));

/**

 * Release a physical block lock if it is held, return it to the lock pool,

 * and null out the caller's reference to it. It must be the last live

 * reference, as if the memory were being freed (the lock memory will

 * re-initialized or zeroed).

 *

 * @param [in]     zone       The physical zone in which the lock was obtained

 * @param [in]     lockedPBN  The physical block number to unlock

 * @param [in,out] lockPtr    The last reference to the lock being released

 **/

void releasePBNLock(PhysicalZone         *zone,

                    PhysicalBlockNumber   lockedPBN,

                    PBNLock             **lockPtr);

/**

 * Dump information about a physical zone to the log for debugging.

 *

 * @param zone   The zone to dump

 **/

void dumpPhysicalZone(const PhysicalZone *zone);

#endif // PHYSICAL_ZONE_H