/*
* 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/request.h#7 $
*/
#ifndef REQUEST_H
#define REQUEST_H
#include "cacheCounters.h"
#include "common.h"
#include "compiler.h"
#include "opaqueTypes.h"
#include "threads.h"
#include "timeUtils.h"
#include "uds.h"
#include "util/funnelQueue.h"
/**
* RequestAction values indicate what action, command, or query is to be
* performed when processing a Request instance.
**/
typedef enum {
// Map the API's UdsCallbackType values directly to a corresponding action.
REQUEST_INDEX = UDS_POST,
REQUEST_UPDATE = UDS_UPDATE,
REQUEST_DELETE = UDS_DELETE,
REQUEST_QUERY = UDS_QUERY,
REQUEST_CONTROL,
// REQUEST_SPARSE_CACHE_BARRIER is the action for the control request used
// by localIndexRouter.
REQUEST_SPARSE_CACHE_BARRIER,
// REQUEST_ANNOUNCE_CHAPTER_CLOSED is the action for the control
// request used by an indexZone to signal the other zones that it
// has closed the current open chapter.
REQUEST_ANNOUNCE_CHAPTER_CLOSED,
} RequestAction;
/**
* The block's rough location in the index, if any.
**/
typedef enum {
/* the block doesn't exist or the location isn't available */
LOC_UNAVAILABLE,
/* if the block was found in the open chapter */
LOC_IN_OPEN_CHAPTER,
/* if the block was found in the dense part of the index */
LOC_IN_DENSE,
/* if the block was found in the sparse part of the index */
LOC_IN_SPARSE
} IndexRegion;
/**
* Abstract request pipeline stages, which can also be viewed as stages in the
* life-cycle of a request.
**/
typedef enum {
STAGE_TRIAGE,
STAGE_INDEX,
STAGE_CALLBACK,
} RequestStage;
/**
* Control message fields for the barrier messages used to coordinate the
* addition of a chapter to the sparse chapter index cache.
**/
typedef struct barrierMessageData {
/** virtual chapter number of the chapter index to add to the sparse cache */
uint64_t virtualChapter;
} BarrierMessageData;
/**
* Control message fields for the chapter closed messages used to inform
* lagging zones of the first zone to close a given open chapter.
**/
typedef struct chapterClosedMessageData {
/** virtual chapter number of the chapter which was closed */
uint64_t virtualChapter;
} ChapterClosedMessageData;
/**
* Union of the all the zone control message fields. The RequestAction field
* (or launch function argument) selects which of the members is valid.
**/
typedef union zoneMessageData {
BarrierMessageData barrier; // for REQUEST_SPARSE_CACHE_BARRIER
ChapterClosedMessageData chapterClosed; // for REQUEST_ANNOUNCE_CHAPTER_CLOSED
} ZoneMessageData;
typedef struct zoneMessage {
/** the index to which the message is directed */
struct index *index;
/** the message specific data */
ZoneMessageData data;
} ZoneMessage;
/**
* Request context for queuing throughout the uds pipeline
*
* XXX Note that the typedef for this struct defines "Request", and that this
* should therefore be "struct request". However, this conflicts with the
* Linux kernel which also has a "struct request". This is a workaround so
* that we can make upstreaming progress. The real solution is to expose
* this structure as the true "struct uds_request" and do a lot of
* renaming.
**/
struct internalRequest {
/*
* The first part of this structure must be exactly parallel to the
* UdsRequest structure, which is part of the public UDS API.
*/
UdsChunkName chunkName; // hash value
UdsChunkData oldMetadata; // metadata from index
UdsChunkData newMetadata; // metadata from request
UdsChunkCallback *callback; // callback method when complete
struct uds_index_session *session; // The public index session
UdsCallbackType type; // the type of request
int status; // success or error code for this request
bool found; // True if the block was found in index
bool update; // move record to newest chapter if found
/*
* The remainder of this structure is private to the UDS implementation.
*/
FunnelQueueEntry requestQueueLink; // for lock-free request queue
Request *nextRequest;
IndexRouter *router;
// Data for control message requests
ZoneMessage zoneMessage;
bool isControlMessage;
bool unbatched; // if true, must wake worker when enqueued
bool requeued;
RequestAction action; // the action for the index to perform
unsigned int zoneNumber; // the zone for this request to use
IndexRegion location; // if and where the block was found
bool slLocationKnown; // slow lane has determined a location
IndexRegion slLocation; // location determined by slowlane
};
typedef void (*RequestRestarter)(Request *);
/**
* Make an asynchronous control message for an index zone and enqueue it for
* processing.
*
* @param action The control action to perform
* @param message The message to send
* @param zone The zone number of the zone to receive the message
* @param router The index router responsible for handling the message
*
* @return UDS_SUCCESS or an error code
**/
int launchZoneControlMessage(RequestAction action,
ZoneMessage message,
unsigned int zone,
IndexRouter *router)
__attribute__((warn_unused_result));
/**
* Free an index request.
*
* @param request The request to free
**/
void freeRequest(Request *request);
/**
* Enqueue a request for the next stage of the pipeline. If there is more than
* one possible queue for a stage, this function uses the request to decide
* which queue should handle it.
*
* @param request The request to enqueue
* @param nextStage The next stage of the pipeline to process the request
**/
void enqueueRequest(Request *request, RequestStage nextStage);
/**
* A method to restart delayed requests.
*
* @param request The request to restart
**/
void restartRequest(Request *request);
/**
* Set the function pointer which is used to restart requests.
* This is needed by albserver code and is used as a test hook by the unit
* tests.
*
* @param restarter The function to call to restart requests.
**/
void setRequestRestarter(RequestRestarter restarter);
/**
* Enter the callback stage of processing for a request, notifying the waiting
* thread if the request is synchronous, freeing the request if it is an
* asynchronous control message, or placing it on the callback queue if it is
* an asynchronous client request.
*
* @param request the request which has completed execution
**/
void enterCallbackStage(Request *request);
/**
* Update the context statistics to reflect the successful completion of a
* client request.
*
* @param request a client request that has successfully completed execution
**/
void updateRequestContextStats(Request *request);
/**
* Compute the CacheProbeType value reflecting the request and page type.
*
* @param request The request being processed, or NULL
* @param isIndexPage Whether the cache probe will be for an index page
*
* @return the cache probe type enumeration
**/
static INLINE CacheProbeType cacheProbeType(Request *request,
bool isIndexPage)
{
if ((request != NULL) && request->requeued) {
return isIndexPage ? CACHE_PROBE_INDEX_RETRY : CACHE_PROBE_RECORD_RETRY;
} else {
return isIndexPage ? CACHE_PROBE_INDEX_FIRST : CACHE_PROBE_RECORD_FIRST;
}
}
#endif /* REQUEST_H */