#ifndef __SFS_XIO_H__ #define __SFS_XIO_H__ /******************************************************************************/ /* */ /* X r d S f s X i o . h h */ /* */ /* (c) 2013 by the Board of Trustees of the Leland Stanford, Jr., University */ /* 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 . */ /* */ /* The copyright holder's institutional names and contributor's names may not */ /* be used to endorse or promote products derived from this software without */ /* specific prior written permission of the institution or contributor. */ /******************************************************************************/ //----------------------------------------------------------------------------- //! XrdSfsXio.hh //! //! This class is used to allow file I/O interfaces to perform exchange buffer //! I/O in order to minimize data copying. When this feature is enabled, the //! XrdSfsInterface::setXio() method is called on a newly created XrdSfsFile //! object. Ideally, all oustanding buffers should be be released when the file //! is closed. Alternatively, the XrdSfsXio::Reclaim() method may be used //! at any time when it is convenient to do so. For best performance, use //! XrdSfsXio::Swap() as it provides memory locality and is kind to the cache. //! Buffer swapping is only supported for common file write operations. //----------------------------------------------------------------------------- //typedef void* XrdSfsXioHandle; typedef class XrdBuffer* XrdSfsXioHandle; class XrdSfsXioImpl; /******************************************************************************/ /* C l a s s X r d S f s X i o */ /******************************************************************************/ class XrdSfsXio { public: //----------------------------------------------------------------------------- //! Get the address and size of the buffer associated with a handle. //! //! @param theHand - The handle associated with the buffer. //! @param buffsz - If not nil, the size of the buffer is returned. The //! size will always be >= to the original data length. //! //! @return A pointer to the buffer. //----------------------------------------------------------------------------- static char *Buffer(XrdSfsXioHandle theHand, int *buffsz=0); //----------------------------------------------------------------------------- //! Claim ownership of the current buffer if it is memory effecient to do so. //! //! @param curBuff - The address of the current buffer. It must match the //! the buffer that was most recently passed to the caller. //! @param datasz - Number of useful bytes in the buffer (i.e. write size). //! @param minasz - Minimum buffer size that would be allocated to copy data. //! //! @return !0 The buffer handle of the current buffer is returned along //! with ownership rights. //! @return =0 Too much memory would be wasted by transferring ownership //! (errno == 0) or an error ocurred (errno != 0). When an //! error see Swap() below for possible types of errors. //----------------------------------------------------------------------------- virtual XrdSfsXioHandle Claim(const char *curBuff, int datasz, int minasz) = 0; //----------------------------------------------------------------------------- //! Return a buffer previously gotten from a Claim() or Swap() call. //! //! @param theHand - The handle associated with the buffer. //----------------------------------------------------------------------------- static void Reclaim(XrdSfsXioHandle theHand); //----------------------------------------------------------------------------- //! Swap the current I/O buffer //! //! @param curBuff - The address of the current buffer. It must match the //! the buffer that was most recently passed to the caller. //! @param oldHand - The handle associated with a buffer returned by a //! previous call to Swap(). A value of zero indicates that //! the caller is taking control of the buffer but has no //! replacement buffer. //! @return !0 The buffer handle of the current buffer is returned along //! with ownership rights. If oldHand was not nil, the //! caller's ownership of the associated buffer is reclaimed. //! @return =0 An error occurred and nothing has changed; errno holds //! the reason for the error. Typically, //! EINVAL - curBuff doe not match current buffer. //! ENOBUFS - not enough memory to give up buffer. //! ENOTSUP - unsupported context for call. //----------------------------------------------------------------------------- virtual XrdSfsXioHandle Swap(const char *curBuff, XrdSfsXioHandle oldHand=0) = 0; //----------------------------------------------------------------------------- //! Constructor and destructor //! //! @param xioimpl Reference to static method implementations. //----------------------------------------------------------------------------- XrdSfsXio(XrdSfsXioImpl &xioimpl); //----------------------------------------------------------------------------- //! Constructor and destructor //----------------------------------------------------------------------------- virtual ~XrdSfsXio() {} }; #endif