/*

 * 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/packer.h#3 $

 */

#ifndef PACKER_H

#define PACKER_H

#include "completion.h"

#include "physicalLayer.h"

#include "statistics.h"

#include "threadConfig.h"

#include "types.h"

enum {

  DEFAULT_PACKER_INPUT_BINS  = 16,

  DEFAULT_PACKER_OUTPUT_BINS = 256,

};

typedef struct packer Packer;

/**

 * Make a new block packer.

 *

 * @param [in]  layer           The physical layer to which compressed blocks

 *                              will be written

 * @param [in]  inputBinCount   The number of partial bins to keep in memory

 * @param [in]  outputBinCount  The number of compressed blocks that can be

 *                              written concurrently

 * @param [in]  threadConfig    The thread configuration of the VDO

 * @param [out] packerPtr       A pointer to hold the new packer

 *

 * @return VDO_SUCCESS or an error

 **/

int makePacker(PhysicalLayer       *layer,

               BlockCount           inputBinCount,

               BlockCount           outputBinCount,

               const ThreadConfig  *threadConfig,

               Packer             **packerPtr)

  __attribute__((warn_unused_result));

/**

 * Free a block packer and null out the reference to it.

 *

 * @param packerPtr  A pointer to the packer to free

 **/

void freePacker(Packer **packerPtr);

/**

 * Check whether the compressed data in a DataVIO will fit in a packer bin.

 *

 * @param dataVIO  The DataVIO

 *

 * @return true if the DataVIO will fit in a bin

 **/

bool isSufficientlyCompressible(DataVIO *dataVIO)

  __attribute__((warn_unused_result));

/**

 * Get the thread ID of the packer's zone.

 *

 * @param packer  The packer

 *

 * @return The packer's thread ID

 **/

ThreadID getPackerThreadID(Packer *packer);

/**

 * Get the current statistics from the packer.

 *

 * @param packer  The packer to query

 *

 * @return a copy of the current statistics for the packer

 **/

PackerStatistics getPackerStatistics(const Packer *packer)

  __attribute__((warn_unused_result));

/**

 * Attempt to rewrite the data in this DataVIO as part of a compressed block.

 *

 * @param dataVIO  The DataVIO to pack

 **/

void attemptPacking(DataVIO *dataVIO);

/**

 * Request that the packer flush asynchronously. All bins with at least two

 * compressed data blocks will be written out, and any solitary pending VIOs

 * will be released from the packer. While flushing is in progress, any VIOs

 * submitted to attemptPacking() will be continued immediately without

 * attempting to pack them.

 *

 * @param packer  The packer to flush

 **/

void flushPacker(Packer *packer);

/**

 * Remove a lock holder from the packer.

 *

 * @param completion  The DataVIO which needs a lock held by a DataVIO in the

 *                    packer. The dataVIO's compressedVIO.lockHolder field will

 *                    point to the DataVIO to remove.

 **/

void removeLockHolderFromPacker(VDOCompletion *completion);

/**

 * Increment the flush generation in the packer. This will also cause the

 * packer to flush so that any VIOs from previous generations will exit the

 * packer.

 *

 * @param packer  The packer

 **/

void incrementPackerFlushGeneration(Packer *packer);

/**

 * Drain the packer by preventing any more VIOs from entering the packer and

 * then flushing.

 *

 * @param packer      The packer to drain

 * @param completion  The completion to finish when the packer has drained

 **/

void drainPacker(Packer *packer, VDOCompletion *completion);

/**

 * Resume a packer which has been suspended.

 *

 * @param packer  The packer to resume

 * @param parent  The completion to finish when the packer has resumed

 *

 * @return VDO_SUCCESS or an error

 **/

void resumePacker(Packer *packer, VDOCompletion *parent);

/**

 * Dump the packer, in a thread-unsafe fashion.

 *

 * @param packer  The packer

 **/

void dumpPacker(const Packer *packer);

#endif /* PACKER_H */