/* IBM_PROLOG_BEGIN_TAG                                                   */
/* This is an automatically generated prolog.                             */
/*                                                                        */
/*                                                                        */
/*                                                                        */
/* Licensed Materials - Property of IBM                                   */
/*                                                                        */
/* (C) COPYRIGHT International Business Machines Corp. 1999,2004          */
/* All Rights Reserved                                                    */
/*                                                                        */
/* US Government Users Restricted Rights - Use, duplication or            */
/* disclosure restricted by GSA ADP Schedule Contract with IBM Corp.      */
/*                                                                        */
/* IBM_PROLOG_END_TAG                                                     */

/* Library to organize and optimize a sequence of accesses to an open file.
   Usage is to first provide a list of n (file offset,length) pairs, then
   call the pixXfer method n times to transfer the data.  Block prefetching is
   taken care of under the covers by the library.  No locking is done, so all
   accesses to or through the library are assumed to be single-threaded. */

#include <sys/types.h>

/* Definition of a single element in an access description list. */
struct pixAccDesc
{
  offset_t off;
  int len;
};


/* State variable for library.  Declare one of these for each open file
   handle that will be used with this library and pass its address as the
   first parameter to all of the pix... calls. */
struct PrefetchedIrregularXfer
{
  /* File information.  File handle and block size for this file. */
  int fHandle;
  int blockSize;

  /* Nonzero if pixXfer() calls should write, 0 for read */
  int isWrite;

  /* Pointer to description of accesses to be performed.  This is just a
     pointer to the accDescP parameter of the last pixDeclareAccesses call. */
  const struct pixAccDesc * accDescP;

  /* Size of the accDescP array */
  int nAccesses;

  /* Access cursor.  Index of the element in the accDescP array that describes
     the next transfer to be performed by the pixXfer() method. */
  int nextAccessIndex;

  /* Prefetch cursor.  Points to the next element in the accDescP array
     that has not yet been included in the blockList array. */
  int nextPrefetchIndex;

  /* Description of blocks corresponding to byte ranges from accDescP.  A
     byte range may translate into more than one block description. */
#define MAX_BLOCKS 64
  struct
  {
    offset_t blockNumber;   /* file block number (file offset / blockSize) */
    int blkOffset;          /* offset in this block of the first byte that
                               will be accessed */
    int blkLen;             /* number of consecutive bytes in this block
                               starting at offset that will be accessed */
  } blockList[MAX_BLOCKS];

  /* Description of entries in blockList that have been given to GPFS
     and accepted using the multiple access range hint.  An empty list is
     represented by setting nAcceptedBlockIndices to 0. */
  int oldestAcceptedBlockIndex;
  int nAcceptedBlockIndices;

  /* Subset of the accepted blockList entries that need to be released
     by the next multiple access range hint.  The first block to be released
     is the one whose index is oldestAcceptedBlockIndex. */
  int nReleaseBlockIndices;

  /* Description of entries in blockList that have been generated from
     entries in accDescP but not yet accepted by the GPFS multiple access
     range hint.  If nPendingBlockIndices is > 0, then firstPendingBlockIndex
     must equal oldestAcceptedBlockIndex+nAcceptedBlockIndices, with all
     indices taken modulo MAX_BLOCKS. */
  int firstPendingBlockIndex;
  int nPendingBlockIndices;

  /* Trace level.  A value of 0 does no tracing to stdout.  Higher values
     trace more things. */
  int verbosity;

  /* Total number of blocks that have been accepted for prefetch minus
     total number of blocks that have been released */
  int netBlocksPrefetched;
};


/* Initialize (must be first call) */
extern void pixInit(struct PrefetchedIrregularXfer * pixP);

/* Declare the sequence of accesses that will be made by subsequent calls
   to the pixXfer method.  The storage passed in will not be modified by
   this class, but must not be deallocated by the caller until all pixXfer
   calls have completed.  Returns an errno value on failure, or 0 if the
   call is successful.  No access in accDescP may be longer than
   MAX_ACCESS_BLOCKS times the block size of this file, or else pixXfer will
   abort the access sequence and return an error. */
#define MAX_ACCESS_BLOCKS 4
extern int pixDeclareAccesses(struct PrefetchedIrregularXfer * pixP,
                              int fHandle, int isWrite, int nAccesses,
                              const struct pixAccDesc * accDescP);

/* Perform the next read or write access defined by an earlier call to
   pixDeclareAccesses.  The buffer is assumed to be large enough to contain
   the next access from the previously declared list.  Returns an errno
   value or zero as the function result.  If zero is returned, stores the
   number of bytes transferred in *nBytesP. */
extern int pixXfer(struct PrefetchedIrregularXfer * pixP, caddr_t bufP,
                   int* nBytesP);

/* Abort pending prefetches and release all prefetched blocks.  Returns
   the state of the PrefetchedIrregularXfer object to what it was just
   after calling pixInit(), except that verbosity is not reset. */
extern void pixTerm(struct PrefetchedIrregularXfer * pixP);

/* Set trace level.  A value of 0 does no tracing, while higher values
   trace more stuff. */
extern void pixSetTraceLevel(struct PrefetchedIrregularXfer * pixP, int level);