/*

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

 */

#ifndef INDEX_ROUTER_H

#define INDEX_ROUTER_H

#include "compiler.h"

#include "index.h"

#include "indexSession.h"

#include "request.h"

/**

 * Callback after a query, update or remove request completes and fills in

 * select fields in the request: status for all requests, oldMetadata and

 * hashExists for query and update requests.

 *

 * @param request     request object.

 **/

typedef void (*IndexRouterCallback)(Request *request);

struct indexRouter {

  IndexRouterCallback  callback;

  unsigned int         zoneCount;

  bool                 needToSave;

  Index               *index;

  RequestQueue        *triageQueue;

  RequestQueue        *zoneQueues[];

};

/**

 * Construct and initialize an IndexRouter instance.

 *

 * @param layout       the IndexLayout that describes the stored index

 * @param config       the configuration to use

 * @param userParams   the index session parameters.  If NULL, the default

 *                     session parameters will be used.

 * @param loadType     selects whether to create, load, or rebuild the index

 * @param loadContext  the index load context to use

 * @param callback     the function to invoke when a request completes or fails

 * @param routerPtr    a pointer in which to store the new router

 *

 * @return UDS_SUCCESS or an error code

 **/

int makeIndexRouter(IndexLayout                  *layout,

                    const Configuration          *config,

                    const struct uds_parameters  *userParams,

                    LoadType                      loadType,

                    IndexLoadContext             *loadContext,

                    IndexRouterCallback           callback,

                    IndexRouter                 **routerPtr)

  __attribute__((warn_unused_result));

/**

 * Executes the index operation for a UDS request and calls the callback upon

 * completion.

 *

 * @param router      The index router.

 * @param request     A pointer to the Request to process.

 **/

void executeIndexRouterRequest(IndexRouter *router, Request *request);

/**

 * Save the index router state to persistent storage.

 *

 * It is the responsibility of the caller to ensure that there are no other

 * uses of the index during a call to this method.  It is necessary that there

 * be no index requests from any block context nor any other attempt to save

 * the index until after a call to saveIndexRouter returns.

 *

 * @param router  the index router to save

 *

 * @return UDS_SUCCESS if successful.

 **/

int saveIndexRouter(IndexRouter *router) __attribute__((warn_unused_result));

/**

 * Destroy the index router and free its memory.

 *

 * @param router  the index router to destroy (may be NULL)

 *

 * @return UDS_SUCCESS if successful.

 **/

void freeIndexRouter(IndexRouter *router);

/**

 * Select and return the request queue responsible for executing the next

 * index stage of a request, updating the request with any associated state

 * (such as the zone number for UDS requests on a local index).

 *

 * @param router     The index router.

 * @param request    The Request destined for the queue.

 * @param nextStage  The next request stage (STAGE_TRIAGE or STAGE_INDEX).

 *

 * @return the next index stage queue (the local triage queue, local zone

 *         queue, or remote RPC send queue)

 **/

RequestQueue *selectIndexRouterQueue(IndexRouter  *router,

                                     Request      *request,

                                     RequestStage  nextStage);

/**

 * Wait for the index router to finish all operations that access a local

 * storage device.

 *

 * @param router    The index router.

 **/

static INLINE void waitForIdleIndexRouter(IndexRouter *router)

{

  waitForIdleChapterWriter(router->index->chapterWriter);

}

#endif /* INDEX_ROUTER_H */