XrdOucCache.hh

Go to the documentation of this file.

#ifndef __XRDOUCCACHE_HH__
#define __XRDOUCCACHE_HH__
/******************************************************************************/
/*                                                                            */
/*                        X r d O u c C a c h e . h h                         */
/*                                                                            */
/* (c) 2026 by the Board of Trustees of the Leland Stanford, Jr., University  */
/*                            All Rights Reserved                             */
/*   Produced by Andrew Hanushevsky for Stanford University under contract    */
/*              DE-AC02-76-SFO0515 with the Department of Energy              */
/*                                                                            */
/* This file is part of the XRootD software suite.                            */
/*                                                                            */
/* XRootD is free software: you can redistribute it and/or modify it under    */
/* the terms of the GNU Lesser General Public License as published by the     */
/* Free Software Foundation, either version 3 of the License, or (at your     */
/* option) any later version.                                                 */
/*                                                                            */
/* XRootD 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 Lesser General Public       */
/* License for more details.                                                  */
/*                                                                            */
/* You should have received a copy of the GNU Lesser General Public License   */
/* along with XRootD in a file called COPYING.LESSER (LGPL license) and file  */
/* COPYING (GPL license).  If not, see <http://www.gnu.org/licenses/>.        */
/*                                                                            */
/* The copyright holder's institutional names and contributor's names may not */
/* specific prior written permission of the institution or contributor.       */
/******************************************************************************/
 
#include <cerrno>
#include <cstdint>
#include <string>
#include <vector>
 
#include "XrdOuc/XrdOucCacheStats.hh"
#include "XrdOuc/XrdOucIOVec.hh"
#include "XrdOuc/XrdOucRange.hh"
 
struct stat;
class  XrdOucEnv;
 
/******************************************************************************/
/*                       X r d O u c C a c h e I O C B                        */
/******************************************************************************/
 
//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------
 
class XrdOucCacheIOCB
{
public:
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
virtual
void     Done(int result) = 0;
 
         XrdOucCacheIOCB() {}
virtual ~XrdOucCacheIOCB() {}
};
 
/******************************************************************************/
/*                       X r d O u c C a c h e I O C D                        */
/******************************************************************************/
 
//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------
 
class XrdOucCacheIOCD
{
public:
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
virtual
void     DetachDone() = 0;
 
         XrdOucCacheIOCD() {}
virtual ~XrdOucCacheIOCD() {}
};
 
/******************************************************************************/
/*                         X r d O u c C a c h e O p                          */
/******************************************************************************/
 
struct XrdOucCacheOp
      {enum Code {QFinfo  = 0,  // Requires a file   target
                  QFSinfo = 1   // Requires a global target
                 };
      };
 
/******************************************************************************/
/*                   C l a s s   X r d O u c C a c h e I O                    */
/******************************************************************************/
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
class XrdOucCacheIO
{
public:
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual bool Detach(XrdOucCacheIOCD &iocd) = 0;
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int  Fcntl(XrdOucCacheOp::Code opc, const std::string& args,
                                                  std::string& resp)
                  {resp = "Function not supported";
                   return -ENOTSUP;
                  }
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
virtual
long long    FSize() = 0;
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int  Fstat(struct stat &sbuff) {(void)sbuff; return 1;}
 
//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------
virtual
const char  *Location(bool refresh=false) {(void)refresh; return "";}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
virtual
const char  *Path() = 0;
 
//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------
 
static const uint64_t forceCS = 0x0000000000000001ULL;
 
virtual int  pgRead(char                  *buff,
                    long long              offs,
                    int                    rdlen,
                    std::vector<uint32_t> &csvec,
                    uint64_t               opts=0,
                    int                   *csfix=0);
 
//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------
 
virtual void pgRead(XrdOucCacheIOCB       &iocb,
                    char                  *buff,
                    long long              offs,
                    int                    rdlen,
                    std::vector<uint32_t> &csvec,
                    uint64_t               opts=0,
                    int                   *csfix=0)
                   {iocb.Done(pgRead(buff, offs, rdlen, csvec, opts, csfix));}
 
//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------
 
virtual int  pgWrite(char                  *buff,
                     long long              offs,
                     int                    wrlen,
                     std::vector<uint32_t> &csvec,
                     uint64_t               opts=0,
                     int                   *csfix=0);
 
//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------
 
virtual void pgWrite(XrdOucCacheIOCB       &iocb,
                     char                  *buff,
                     long long              offs,
                     int                    wrlen,
                     std::vector<uint32_t> &csvec,
                     uint64_t               opts=0,
                     int                   *csfix=0)
                    {iocb.Done(pgWrite(buff, offs, wrlen, csvec, opts, csfix));}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
static const int SingleUse = 0x0001; 
 
virtual void Preread(long long offs, int rlen, int opts=0)
                    {(void)offs; (void)rlen; (void)opts;}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual void Preread(XrdOucRangeList& rlist)
                    {for (auto it = rlist.begin(); it != rlist.end(); it++)
                         Preread(it->offset, it->size);
                    }
 
//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------
 
struct aprParms
      {int   Trigger;   // preread if (rdln < Trigger)        (0 -> pagesize+1)
       int   prRecalc;  // Recalc pr efficiency every prRecalc bytes   (0->50M)
       int   Reserve1;
       short minPages;  // If rdln/pgsz < min,  preread minPages       (0->off)
       signed
       char  minPerf;   // Minimum auto preread performance required   (0->n/a)
       char  Reserve2;
       void *Reserve3;
 
             aprParms() : Trigger(0),  prRecalc(0), Reserve1(0),
                          minPages(0), minPerf(90), Reserve2(0), Reserve3(0) {}
      };
 
virtual void Preread(aprParms &Parms) { (void)Parms; }
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int  Read (char *buff, long long offs, int rlen) = 0;
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual void Read (XrdOucCacheIOCB &iocb, char *buff, long long offs, int rlen)
                  {iocb.Done(Read(buff, offs, rlen));}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int  ReadV(const XrdOucIOVec *readV, int rnum);
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual void ReadV(XrdOucCacheIOCB &iocb, const XrdOucIOVec *readV, int rnum)
                  {iocb.Done(ReadV(readV, rnum));}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int  Sync() = 0;
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual void Sync(XrdOucCacheIOCB &iocb) {iocb.Done(Sync());}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int  Trunc(long long offs) = 0;
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual void Trunc(XrdOucCacheIOCB &iocb, long long offs)
                  {iocb.Done(Trunc(offs));}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual void Update(XrdOucCacheIO &iocp) {}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int  Write(char *buff, long long offs, int wlen) = 0;
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual void Write(XrdOucCacheIOCB &iocb, char *buff, long long offs, int wlen)
                  {iocb.Done(Write(buff, offs, wlen));}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int  WriteV(const XrdOucIOVec *writV, int wnum);
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual void WriteV(XrdOucCacheIOCB &iocb, const XrdOucIOVec *writV, int wnum)
                  {iocb.Done(WriteV(writV, wnum));}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
            XrdOucCacheIO() {}
protected:
virtual    ~XrdOucCacheIO() {}  // Always use Detach() instead of direct delete!
};
 
/******************************************************************************/
/*                     C l a s s   X r d O u c C a c h e                      */
/******************************************************************************/
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
class XrdOucCache
{
public:
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
static const int optFIS = 0x0001; 
static const int optRW  = 0x0004; 
static const int optNEW = 0x0014; 
static const int optWIN = 0x0024; 
 
virtual
XrdOucCacheIO *Attach(XrdOucCacheIO *ioP, int opts=0) = 0;
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int  Fcntl(XrdOucCacheOp::Code opc, const std::string& args,
                                                  std::string& resp)
                  {resp = "Function not supported";
                   return -ENOTSUP;
                  }
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
enum LFP_Reason {ForAccess=0, ForInfo, ForPath};
 
virtual int    LocalFilePath(const char *url, char *buff=0, int blen=0,
                             LFP_Reason why=ForAccess, bool forall=false)
                             {(void)url; (void)buff; (void)blen; (void)why;
                              (void)forall;
                             if (buff && blen > 0) *buff = 0;
                              return -ENOTSUP;
                             }
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int    Prepare(const char *url, int oflags, mode_t mode)
                      {(void)url; (void)oflags; (void)mode; return 0;}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int   Rename(const char* oldp, const char* newp)
                    {(void)oldp; (void)newp; return 0;}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int   Rmdir(const char* dirp) {(void)dirp; return 0;}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int  Stat(const char *url, struct stat &sbuff)
                 {(void)url; (void)sbuff; return 1;}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int   Truncate(const char* path, off_t size)
                      {(void)path; (void)size; return 0;}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual int   Unlink(const char* path) {(void)path; return 0;}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
enum XeqCmd {xeqNoop = 0};
 
virtual int    Xeq(XeqCmd cmd, char *arg, int arglen)
                  {(void)cmd; (void)arg; (void)arglen; return -ENOTSUP;}
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
XrdOucCacheStats Statistics;
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
const char CacheType[8];
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
               XrdOucCache(const char *ctype) : CacheType{}
//                        : CacheType({'\0','\0','\0','\0','\0','\0','\0','\0'})
                          {strncpy(const_cast<char *>(CacheType), ctype,
                                   sizeof(CacheType));
                           const_cast<char *>(CacheType)[sizeof(CacheType)-1]=0;
                          }
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
virtual       ~XrdOucCache() {}
};
 
/******************************************************************************/
/*               C r e a t i n g   C a c h e   P l u g - I n s                */
/******************************************************************************/
 
//------------------------------------------------------------------------------
 
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
typedef XrdOucCache *(*XrdOucCache_t)(XrdSysLogger *Logger, const char *Config,
                                      const char   *Parms,  XrdOucEnv  *envP);
 
#endif