/*

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

 */

#ifndef DIRTY_LISTS_H

#define DIRTY_LISTS_H

#include "ringNode.h"

#include "types.h"

/**

 * A collection of lists of dirty elements ordered by age. An element is always

 * placed on the oldest list in which it was dirtied (moving between lists or

 * removing altogether is cheap). Whenever the current period is advanced, any

 * elements older than the maxium age are expired. If an element is to be added

 * with a dirty age older than the maximum age, it is expired immediately.

 **/

typedef struct dirtyLists DirtyLists;

/**

 * A function which will be called with a ring of dirty elements which have

 * been expired. All of the expired elements must be removed from the ring

 * before this function returns.

 *

 * @param expired  The list of expired elements

 * @param context  The context for the callback

 **/

typedef void DirtyCallback(RingNode *expired, void *context);

/**

 * Construct a new set of dirty lists.

 *

 * @param [in]  maximumAge     The age at which an element will be expired

 * @param [in]  callback       The function to call when a set of elements have

 *                             expired

 * @param [in]  context        The context for the callback

 * @param [out] dirtyListsPtr  A pointer to hold the new DirtyLists

 *

 * @return VDO_SUCCESS or an error

 **/

int makeDirtyLists(BlockCount      maximumAge,

                   DirtyCallback  *callback,

                   void           *context,

                   DirtyLists    **dirtyListsPtr)

  __attribute__((warn_unused_result));

/**

 * Free a set of dirty lists and null out the pointer to them.

 *

 * @param dirtyListsPtr A pointer to the dirty lists to be freed

 **/

void freeDirtyLists(DirtyLists **dirtyListsPtr);

/**

 * Set the current period. This function should only be called once.

 *

 * @param dirtyLists  The dirtyLists

 * @param period      The current period

 **/

void setCurrentPeriod(DirtyLists *dirtyLists, SequenceNumber period);

/**

 * Add an element to the dirty lists.

 *

 * @param dirtyLists  The DirtyLists receiving the element

 * @param node        The RingNode of the element to add

 * @param oldPeriod   The period in which the element was previous dirtied,

 *                    or 0 if it was not dirty

 * @param newPeriod   The period in which the element has now been dirtied,

 *                    or 0 if it does not hold a lock

 **/

void addToDirtyLists(DirtyLists     *dirtyLists,

                     RingNode       *node,

                     SequenceNumber  oldPeriod,

                     SequenceNumber  newPeriod);

/**

 * Advance the current period. If the current period is greater than the number

 * of lists, expire the oldest lists.

 *

 * @param dirtyLists  The DirtyLists to advance

 * @param period      The new current period

 **/

void advancePeriod(DirtyLists *dirtyLists, SequenceNumber period);

/**

 * Flush all dirty lists. This will cause the period to be advanced past the

 * current period.

 *

 * @param dirtyLists  The dirtyLists to flush

 **/

void flushDirtyLists(DirtyLists *dirtyLists);

#endif // DIRTY_LISTS_H