/* * 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/indexState.h#5 $ */ #ifndef INDEX_STATE_H #define INDEX_STATE_H 1 #include "buffer.h" #include "indexComponent.h" /** * Used here and in SingleFileLayout. **/ typedef enum { IS_SAVE, IS_CHECKPOINT, NO_SAVE = 9999, } IndexSaveType; /* * Used in getStateIndexStateBuffer to identify whether the index state buffer * is for the index being loaded or the index being saved. */ typedef enum { IO_READ = 0x1, IO_WRITE = 0x2, } IOAccessMode; /** * The index state structure controls the loading and saving of the index * state. **/ typedef struct indexState { struct indexLayout *layout; unsigned int zoneCount; // number of index zones to use unsigned int loadZones; unsigned int loadSlot; unsigned int saveSlot; unsigned int count; // count of registered entries (<= length) unsigned int length; // total span of array allocation bool saving; // incremental save in progress IndexComponent *entries[]; // array of index component entries } IndexState; /** * Make an index state object, * * @param [in] layout The index layout. * @param [in] numZones The number of zones to use. * @param [in] maxComponents The maximum number of components to be handled. * @param [out] statePtr Where to store the index state object. * * @return UDS_SUCCESS or an error code **/ int makeIndexState(struct indexLayout *layout, unsigned int numZones, unsigned int maxComponents, IndexState **statePtr) __attribute__((warn_unused_result)); /** * Free an index state (generically). * * @param statePtr The pointer to the index state to be freed and * set to NULL. **/ void freeIndexState(IndexState **statePtr); /** * Add an index component to an index state. * * @param state The index directory in which to add this component. * @param info The index component file specification. * @param data The per-component data structure. * @param context The load/save context of the component. * * @return UDS_SUCCESS or an error code. **/ int addIndexStateComponent(IndexState *state, const IndexComponentInfo *info, void *data, void *context) __attribute__((warn_unused_result)); /** * Load index state * * @param state The index state. * @param replayPtr If set, the place to hold whether a replay is required. * * @return UDS_SUCCESS or error **/ int loadIndexState(IndexState *state, bool *replayPtr) __attribute__((warn_unused_result)); /** * Save the current index state, including the open chapter. * * @param state The index state. * * @return UDS_SUCCESS or error **/ int saveIndexState(IndexState *state) __attribute__((warn_unused_result)); /** * Prepare to save the index state. * * @param state the index state * @param saveType whether a checkpoint or save * * @return UDS_SUCCESS or an error code **/ int prepareToSaveIndexState(IndexState *state, IndexSaveType saveType) __attribute__((warn_unused_result)); /** * Write index checkpoint non-incrementally (for testing). * * @param state The index state. * * @return UDS_SUCCESS or error **/ int writeIndexStateCheckpoint(IndexState *state) __attribute__((warn_unused_result)); /** * Sets up an index state checkpoint which will proceed incrementally. * May create the directory but does not actually write any data. * * @param state The index state. * * @return UDS_SUCCESS or an error code. **/ int startIndexStateCheckpoint(IndexState *state) __attribute__((warn_unused_result)); /** * Perform operations on index state checkpoints that are synchronized to * the chapter writer thread. * * @param state The index state. * * @return UDS_SUCCESS or an error code. **/ int performIndexStateCheckpointChapterSynchronizedSaves(IndexState *state) __attribute__((warn_unused_result)); /** * Performs zone-specific (and, for zone 0, general) incremental checkpointing. * * @param [in] state The index state. * @param [in] zone The zone number. * @param [out] completed Set to whether the checkpoint has completed * for this zone. * * @return UDS_SUCCESS or an error code. **/ int performIndexStateCheckpointInZone(IndexState *state, unsigned int zone, CompletionStatus *completed) __attribute__((warn_unused_result)); /** * Force the completion of an incremental index state checkpoint * for a particular zone. * * @param [in] state The index state. * @param [in] zone The zone number. * @param [out] completed Set to whether the checkpoint has completed * for this zone. * * @return UDS_SUCCESS or an error code. **/ int finishIndexStateCheckpointInZone(IndexState *state, unsigned int zone, CompletionStatus *completed) __attribute__((warn_unused_result)); /** * Force the completion of an incremental index state checkpoint once * all zones are completed. * * @param [in] state The index state. * * @return UDS_SUCCESS or an error code. **/ int finishIndexStateCheckpoint(IndexState *state) __attribute__((warn_unused_result)); /** * Aborts an index state checkpoint which is proceeding incrementally * for a particular zone. * * @param [in] state The index state. * @param [in] zone The zone number. * @param [out] completed Set to whether the checkpoint has completed or * aborted for this zone. * * @return UDS_SUCCESS or an error code. **/ int abortIndexStateCheckpointInZone(IndexState *state, unsigned int zone, CompletionStatus *completed); /** * Aborts an index state checkpoint which is proceeding incrementally, * once all the zones are aborted. * * @param [in] state The index state. * * @return UDS_SUCCESS or an error code. **/ int abortIndexStateCheckpoint(IndexState *state); /** * Remove or disable the index state data, for testing. * * @param state The index state * * @return UDS_SUCCESS or an error code * * @note the return value of this function is frequently ignored **/ int discardIndexStateData(IndexState *state); /** * Discard the last index state save, for testing. * * @param state The index state * * @return UDS_SUCCESS or an error code * * @note the return value of this function is frequently ignored **/ int discardLastIndexStateSave(IndexState *state); /** * Find index component, for testing. * * @param state The index state * @param info The index component file specification * * @return The index component, or NULL if not found **/ IndexComponent *findIndexComponent(const IndexState *state, const IndexComponentInfo *info) __attribute__((warn_unused_result)); /** * Get the indexStateBuffer for a specified mode. * * @param state The index state. * @param mode One of IO_READ or IO_WRITE. * * @return the index state buffer **/ Buffer *getStateIndexStateBuffer(IndexState *state, IOAccessMode mode) __attribute__((warn_unused_result)); /** * Open a BufferedReader for a specified state, kind, and zone. * This helper function is used by IndexComponent. * * @param state The index state. * @param kind The kind if index save region to open. * @param zone The zone number for the region. * @param readerPtr Where to store the BufferedReader. * * @return UDS_SUCCESS or an error code. **/ int openStateBufferedReader(IndexState *state, RegionKind kind, unsigned int zone, BufferedReader **readerPtr) __attribute__((warn_unused_result)); /** * Open a BufferedWriter for a specified state, kind, and zone. * This helper function is used by IndexComponent. * * @param state The index state. * @param kind The kind if index save region to open. * @param zone The zone number for the region. * @param writerPtr Where to store the BufferedWriter. * * @return UDS_SUCCESS or an error code. **/ int openStateBufferedWriter(IndexState *state, RegionKind kind, unsigned int zone, BufferedWriter **writerPtr) __attribute__((warn_unused_result)); #endif // INDEX_STATE_H