Skip to content

Commit

Permalink
XrdApps::JCache: add documentation to File header
Browse files Browse the repository at this point in the history
  • Loading branch information
@apeters1971
apeters1971 committed Jun 7, 2024
1 parent c8f7130 commit 8a40aba
Showing 1 changed file with 84 additions and 17 deletions.
101 changes: 84 additions & 17 deletions src/XrdApps/XrdClJCachePlugin/file/XrdClJCacheFile.hh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,11 @@
namespace XrdCl
{
//----------------------------------------------------------------------------
//! RAIN file plugin
//! JCache file plugin
//! This XRootD Client Plugin provides a client side read cache.
//! There are two ways of caching, which can be configured individually:
//! - Read Journal Cache (journalling)
//! - Vector Read Cache (vector read responses are stored in binary blobs)
//----------------------------------------------------------------------------
class JCacheFile: public XrdCl::FilePlugIn
{
Expand All @@ -58,7 +62,12 @@ public:


//----------------------------------------------------------------------------
//! Open
//! @brief Open a file by URL
//! @param url URL of the file
//! @param flags Open flags
//! @param mode Access mode
//! @param handler Response handler
//! @param timeout Timeout in seconds
//----------------------------------------------------------------------------
virtual XRootDStatus Open(const std::string& url,
OpenFlags::Flags flags,
Expand All @@ -68,22 +77,32 @@ public:


//----------------------------------------------------------------------------
//! Close
//! @brief Close a file
//! @param handler Response handler
//! @param timeout Timeout in seconds
//----------------------------------------------------------------------------
virtual XRootDStatus Close(ResponseHandler* handler,
uint16_t timeout);


//----------------------------------------------------------------------------
//! Stat
//! @brief Stat a file
//! @param force Force stat
//! @param handler Response handler
//! @param timeout Timeout in seconds
//----------------------------------------------------------------------------
virtual XRootDStatus Stat(bool force,
ResponseHandler* handler,
uint16_t timeout);


//----------------------------------------------------------------------------
//! Read
//! @brief Read
//! @param offset Offset in bytes
//! @param size Size in bytes
//! @param buffer Buffer to read into
//! @param handler Response handler
//! @param timeout Timeout in seconds
//----------------------------------------------------------------------------
virtual XRootDStatus Read(uint64_t offset,
uint32_t size,
Expand All @@ -93,7 +112,12 @@ public:


//----------------------------------------------------------------------------
//! Write
//! @brief Write
//! @param offset Offset in bytes
//! @param size Size in bytes
//! @param buffer Buffer to write from
//! @param handler Response handler
//! @param timeout Timeout in seconds
//----------------------------------------------------------------------------
virtual XRootDStatus Write(uint64_t offset,
uint32_t size,
Expand All @@ -103,30 +127,44 @@ public:


//----------------------------------------------------------------------------
//! Sync
//! @brief Sync
//! @param handler Response handler
//! @param timeout Timeout in seconds
//----------------------------------------------------------------------------
virtual XRootDStatus Sync(ResponseHandler* handler,
uint16_t timeout);


//----------------------------------------------------------------------------
//! Truncate
//! @brief Truncate
//! @param size Size in bytes
//! @param handler Response handler
//! @param timeout Timeout in seconds
//----------------------------------------------------------------------------
virtual XRootDStatus Truncate(uint64_t size,
ResponseHandler* handler,
uint16_t timeout);


//----------------------------------------------------------------------------
//! VectorRead
//! @brief VectorRead
//! @param chunks Chunks to read
//! @param buffer Buffer to read into
//! @param handler Response handler
//! @param timeout Timeout in seconds
//----------------------------------------------------------------------------
virtual XRootDStatus VectorRead(const ChunkList& chunks,
void* buffer,
ResponseHandler* handler,
uint16_t timeout);

//------------------------------------------------------------------------
//! PgRead
//! @brief PgRead
//! @param offset Offset in bytes
//! @param size Size in bytes
//! @param buffer Buffer to read into
//! @param handler Response handler
//! @param timeout Timeout in seconds
//------------------------------------------------------------------------
virtual XRootDStatus PgRead( uint64_t offset,
uint32_t size,
Expand All @@ -135,7 +173,12 @@ public:
uint16_t timeout ) override;

//------------------------------------------------------------------------
//! PgWrite
//! @brief PgWrite
//! @param offset Offset in bytes
//! @param nbpgs Number of pages
//! @param buffer Buffer to write from
//! @param handler Response handler
//! @param timeout Timeout in seconds
//------------------------------------------------------------------------
virtual XRootDStatus PgWrite( uint64_t offset,
uint32_t nbpgs,
Expand All @@ -146,22 +189,27 @@ public:


//------------------------------------------------------------------------
//! Fcntl
//! @brief Fcntl
//! @param arg Argument
//! @param handler Response handler
//! @param timeout Timeout in seconds
//------------------------------------------------------------------------
virtual XRootDStatus Fcntl(const Buffer& arg,
ResponseHandler* handler,
uint16_t timeout);


//----------------------------------------------------------------------------
//! Visa
//! @brief Visa
//! @param handler Response handler
//! @param timeout Timeout in seconds
//----------------------------------------------------------------------------
virtual XRootDStatus Visa(ResponseHandler* handler,
uint16_t timeout);


//----------------------------------------------------------------------------
//! IsOpen
//! @brief check if file is open
//----------------------------------------------------------------------------
virtual bool IsOpen() const;

Expand All @@ -181,28 +229,34 @@ public:


//----------------------------------------------------------------------------
//! validate the local cache
//! @brief validate the local cache
//----------------------------------------------------------------------------
inline bool IsValid()
{
return true;
}

//----------------------------------------------------------------------------
//! set the local cache path
//! @brief set the local cache path and enable/disable journal/vector caches
//! @param path Local cache path
//! @param journal Enable/disable journal cache
//! @param vector Enable/disable vector cache
//----------------------------------------------------------------------------

static void SetCache(const std::string& path) { sCachePath = path; }
static void SetJournal(const bool& value) { sEnableJournalCache = value; }
static void SetVector(const bool& value) { sEnableVectorCache = value; }

//----------------------------------------------------------------------------
//! get the local cache path
//! @brief static members pointing to cache settings
//----------------------------------------------------------------------------
static std::string sCachePath;
static bool sEnableVectorCache;
static bool sEnableJournalCache;

//----------------------------------------------------------------------------
//! @brief log cache hit statistics
//----------------------------------------------------------------------------
void LogStats() {
mLog->Info(1, "JCache : read:readv-ops:readv-read-ops: %lu:%lu:%lus hit-rate: total [read/readv]=%.02f%% [%.02f%%/%.02f%%] remote-bytes-read/readv: %lu / %lu cached-bytes-read/readv: %lu / %lu",
pStats.readOps.load(),
Expand All @@ -216,6 +270,8 @@ public:
pStats.bytesCached.load(),
pStats.bytesCachedV.load());
}


//! structure about cache hit statistics
struct CacheStats {
CacheStats() :
Expand Down Expand Up @@ -248,18 +304,29 @@ public:
};
private:

//! @brief attach for read
bool AttachForRead();

//! @brief atomic variable to track if file is attached for read
std::atomic<bool> mAttachedForRead;
//! @brief mutex protecting cache attach procedure
std::mutex mAttachMutex;
//! @brief open flags used in Open
OpenFlags::Flags mFlags;
//! @brief boolean to track if file is open
bool mIsOpen;
//! @brief pointer to the remote file
XrdCl::File* pFile;
//! @brief URL of the remote file
std::string pUrl;
//! @brief instance of a local journal for this file
Journal pJournal;
//! @brief path to the journal of this file
std::string pJournalPath;
//! @brief pointer to logging object
Log* mLog;

//! @brief cache hit statistics
CacheStats pStats;
};

Expand Down

0 comments on commit 8a40aba

Please sign in to comment.