/*
* 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/uds-releases/jasper/src/uds/index.h#3 $
*/
#ifndef INDEX_H
#define INDEX_H
#include "chapterWriter.h"
#include "indexLayout.h"
#include "indexSession.h"
#include "indexZone.h"
#include "loadType.h"
#include "masterIndexOps.h"
#include "volume.h"
/**
* Index checkpoint state private to indexCheckpoint.c.
**/
typedef struct indexCheckpoint IndexCheckpoint;
typedef struct index {
bool existed;
bool hasSavedOpenChapter;
LoadType loadedType;
IndexLoadContext *loadContext;
IndexLayout *layout;
IndexState *state;
MasterIndex *masterIndex;
Volume *volume;
unsigned int zoneCount;
IndexZone **zones;
/*
* ATTENTION!!!
* The meaning of the next two fields has changed.
*
* They now represent the oldest and newest chapters only at load time,
* and when the index is quiescent. At other times, they may lag individual
* zones' views of the index depending upon the progress made by the chapter
* writer.
*/
uint64_t oldestVirtualChapter;
uint64_t newestVirtualChapter;
uint64_t lastCheckpoint;
uint64_t prevCheckpoint;
ChapterWriter *chapterWriter;
// checkpoint state used by indexCheckpoint.c
IndexCheckpoint *checkpoint;
} Index;
/**
* Construct a new index from the given configuration.
*
* @param layout The index layout
* @param config The configuration to use
* @param userParams The index session parameters. If NULL, the default
* session parameters will be used.
* @param zoneCount The number of zones for this index to use
* @param loadType How to create the index: it can be create only, allow
* loading from files, and allow rebuilding from the volume
* @param loadContext The load context to use
* @param newIndex A pointer to hold a pointer to the new index
*
* @return UDS_SUCCESS or an error code
**/
int makeIndex(IndexLayout *layout,
const Configuration *config,
const struct uds_parameters *userParams,
unsigned int zoneCount,
LoadType loadType,
IndexLoadContext *loadContext,
Index **newIndex)
__attribute__((warn_unused_result));
/**
* Save an index.
*
* Before saving an index and while saving an index, the caller must ensure
* that there are no index requests in progress.
*
* Some users follow saveIndex immediately with a freeIndex. But some tests
* use the IndexLayout to modify the saved index. The Index will then have
* some cached information that does not reflect these updates.
*
* @param index The index to save
*
* @return UDS_SUCCESS if successful
**/
int saveIndex(Index *index) __attribute__((warn_unused_result));
/**
* Clean up the index and its memory.
*
* @param index The index to destroy.
**/
void freeIndex(Index *index);
/**
* Perform the index operation specified by the action field of a UDS request.
*
* For UDS API requests, this searches the index for the chunk name in the
* request. If the chunk name is already present in the index, the location
* field of the request will be set to the IndexRegion where it was found. If
* the action is not DELETE, the oldMetadata field of the request will also be
* filled in with the prior metadata for the name.
*
* If the API request action is:
*
* REQUEST_INDEX, a record will be added to the open chapter with the
* metadata in the request for new records, and the existing metadata for
* existing records
*
* REQUEST_UPDATE, a record will be added to the open chapter with the
* metadata in the request
*
* REQUEST_QUERY, if the update flag is set in the request, any record
* found will be moved to the open chapter. In all other cases the contents
* of the index will remain unchanged.
*
* REQUEST_REMOVE, the any entry with the name will removed from the index
*
* For non-API requests, no chunk name search is involved.
*
* @param index The index
* @param request The originating request
*
* @return UDS_SUCCESS, UDS_QUEUED, or an error code
**/
int dispatchIndexRequest(Index *index, Request *request)
__attribute__((warn_unused_result));
/**
* Internal helper to prepare the index for saving.
*
* @param index the index
* @param checkpoint whether the save is a checkpoint
* @param openChapterNumber the virtual chapter number of the open chapter
**/
void beginSave(Index *index, bool checkpoint, uint64_t openChapterNumber);
/**
* Replay the volume file to repopulate the master index.
*
* @param index The index
* @param fromVCN The virtual chapter to start replaying
*
* @return UDS_SUCCESS if successful
**/
int replayVolume(Index *index, uint64_t fromVCN)
__attribute__((warn_unused_result));
/**
* Gather statistics from the master index, volume, and cache.
*
* @param index The index
* @param counters the statistic counters for the index
**/
void getIndexStats(Index *index, UdsIndexStats *counters);
/**
* Set lookup state for this index. Disabling lookups means assume
* all records queried are new (intended for debugging uses, e.g.,
* albfill).
*
* @param index The index
* @param enabled The new lookup state
**/
void setIndexLookupState(Index *index, bool enabled);
/**
* Advance the newest virtual chapter. If this will overwrite the oldest
* virtual chapter, advance that also.
*
* @param index The index to advance
**/
void advanceActiveChapters(Index *index);
/**
* Triage an index request, deciding whether it requires that a sparse cache
* barrier message precede it.
*
* This resolves the chunk name in the request in the master index,
* determining if it is a hook or not, and if a hook, what virtual chapter (if
* any) it might be found in. If a virtual chapter is found, it checks whether
* that chapter appears in the sparse region of the index. If all these
* conditions are met, the (sparse) virtual chapter number is returned. In all
* other cases it returns <code>UINT64_MAX</code>.
*
* @param index the index that will process the request
* @param request the index request containing the chunk name to triage
*
* @return the sparse chapter number for the sparse cache barrier message, or
* <code>UINT64_MAX</code> if the request does not require a barrier
**/
uint64_t triageIndexRequest(Index *index, Request *request)
__attribute__((warn_unused_result));
#endif /* INDEX_H */