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

#ifndef REFERENCE_OPERATION_H
#define REFERENCE_OPERATION_H

#include "types.h"

typedef struct referenceOperation ReferenceOperation;

/**
 * Get the PBNLock associated with a ReferenceOperation.
 *
 * @param operation  The ReferenceOperation
 *
 * @return The PBNLock on the block of a ReferenceOperation or NULL if there
 *         isn't one
 **/
typedef PBNLock *PBNLockGetter(ReferenceOperation operation);

/**
 * The current operation on a physical block (from the point of view of the
 * DataVIO doing the operation)
 **/
struct referenceOperation {
  /** The operation being performed */
  JournalOperation     type;
  /** The PBN of the block being operated on */
  PhysicalBlockNumber  pbn;
  /** The mapping state of the block being operated on */
  BlockMappingState    state;
  /** A function to use to get any PBNLock associated with this operation */
  PBNLockGetter       *lockGetter;
  /** The context to pass to the PBNLockGetter */
  void                *context;
};

/**
 * Get the PBNLock associated with the current ReferenceOperation.
 *
 * @param operation  The reference operation
 *
 * @return The PBNLock on the block of the current operation or NULL if there
 *         isn't one
 **/
__attribute__((warn_unused_result))
static inline
PBNLock *getReferenceOperationPBNLock(ReferenceOperation operation)
{
  return ((operation.lockGetter == NULL)
          ? NULL : operation.lockGetter(operation));
}

/**
 * Set up a ReferenceOperation for which we already have the lock.
 *
 * @param type       The type of operation
 * @param pbn        The PBN of the block on which to operate
 * @param state      The mapping state of the block on which to operate
 * @param lock       The PBNLock to associate with the operation
 * @param operation  The ReferenceOperation to set up
 **/
void setUpReferenceOperationWithLock(JournalOperation     type,
                                     PhysicalBlockNumber  pbn,
                                     BlockMappingState    state,
                                     PBNLock             *lock,
                                     ReferenceOperation  *operation);

/**
 * Set up a ReferenceOperation for which we will need to look up the lock later.
 *
 * @param type       The type of operation
 * @param pbn        The PBN of the block on which to operate
 * @param state      The mapping state of the block on which to operate
 * @param zone       The PhysicalZone from which the PBNLock can be retrieved
 *                   when needed
 * @param operation  The ReferenceOperation to set up
 **/
void setUpReferenceOperationWithZone(JournalOperation     type,
                                     PhysicalBlockNumber  pbn,
                                     BlockMappingState    state,
                                     PhysicalZone        *zone,
                                     ReferenceOperation  *operation);

#endif // REFERENCE_OPERATION_H