/*

 * 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/slabScrubber.h#4 $

 */

#ifndef SLAB_SCRUBBER_H

#define SLAB_SCRUBBER_H

#include "completion.h"

#include "types.h"

#include "waitQueue.h"

/**

 * Create a slab scrubber

 *

 * @param layer             The physical layer of the VDO

 * @param slabJournalSize   The size of a slab journal in blocks

 * @param readOnlyNotifier  The context for entering read-only mode

 * @param scrubberPtr       A pointer to hold the scrubber

 *

 * @return VDO_SUCCESS or an error

 **/

int makeSlabScrubber(PhysicalLayer     *layer,

                     BlockCount         slabJournalSize,

                     ReadOnlyNotifier  *readOnlyNotifier,

                     SlabScrubber     **scrubberPtr)

  __attribute__((warn_unused_result));

/**

 * Free a slab scrubber and null out the reference to it.

 *

 * @param scrubberPtr  A pointer to the scrubber to destroy

 **/

void freeSlabScrubber(SlabScrubber **scrubberPtr);

/**

 * Check whether a scrubber has slabs to scrub.

 *

 * @param scrubber  The scrubber to check

 *

 * @return true if the scrubber has slabs to scrub

 **/

bool hasSlabsToScrub(SlabScrubber *scrubber)

  __attribute__((warn_unused_result));

/**

 * Register a slab with a scrubber.

 *

 * @param scrubber      The scrubber

 * @param slab          The slab to scrub

 * @param highPriority  true if the slab should be put on the

 *                      high-priority queue

 **/

void registerSlabForScrubbing(SlabScrubber *scrubber,

                              Slab         *slab,

                              bool          highPriority);

/**

 * Scrub all the slabs which have been registered with a slab scrubber.

 *

 * @param scrubber      The scrubber

 * @param parent        The object to notify when scrubbing is complete

 * @param callback      The function to run when scrubbing is complete

 * @param errorHandler  The handler for scrubbing errors

 **/

void scrubSlabs(SlabScrubber *scrubber,

                void         *parent,

                VDOAction    *callback,

                VDOAction    *errorHandler);

/**

 * Scrub any slabs which have been registered at high priority with a slab

 * scrubber.

 *

 * @param scrubber         The scrubber

 * @param scrubAtLeastOne  true if one slab should always be

 *                         scrubbed, even if there are no high-priority slabs

 *                         (and there is at least one low priority slab)

 * @param parent           The completion to notify when scrubbing is complete

 * @param callback         The function to run when scrubbing is complete

 * @param errorHandler     The handler for scrubbing errors

 **/

void scrubHighPrioritySlabs(SlabScrubber  *scrubber,

                            bool           scrubAtLeastOne,

                            VDOCompletion *parent,

                            VDOAction     *callback,

                            VDOAction     *errorHandler);

/**

 * Tell the scrubber to stop scrubbing after it finishes the slab it is

 * currently working on.

 *

 * @param scrubber  The scrubber to stop

 * @param parent    The completion to notify when scrubbing has stopped

 **/

void stopScrubbing(SlabScrubber *scrubber, VDOCompletion *parent);

/**

 * Tell the scrubber to resume scrubbing if it has been stopped.

 *

 * @param scrubber  The scrubber to resume

 * @param parent    The object to notify once scrubbing has resumed

 **/

void resumeScrubbing(SlabScrubber *scrubber, VDOCompletion *parent);

/**

 * Wait for a clean slab.

 *

 * @param scrubber  The scrubber on which to wait

 * @param waiter    The waiter

 *

 * @return VDO_SUCCESS if the waiter was queued, VDO_NO_SPACE if there are no

 *         slabs to scrub, and some other error otherwise

 **/

int enqueueCleanSlabWaiter(SlabScrubber *scrubber, Waiter *waiter);

/**

 * Get the number of slabs that are unrecovered or being scrubbed.

 *

 * @param scrubber  The scrubber to query

 *

 * @return the number of slabs that are unrecovered or being scrubbed

 **/

SlabCount getScrubberSlabCount(const SlabScrubber *scrubber)

  __attribute__((warn_unused_result));

/**

 * Dump information about a slab scrubber to the log for debugging.

 *

 * @param scrubber   The scrubber to dump

 **/

void dumpSlabScrubber(const SlabScrubber *scrubber);

#endif /* SLAB_SCRUBBER_H */