00001 #ifndef __XRDOUCCACHEDRAM_HH__ 00002 #define __XRDOUCCACHEDRAM_HH__ 00003 /******************************************************************************/ 00004 /* */ 00005 /* X r d O u c C a c h e D r a m . h h */ 00006 /* */ 00007 /* (c) 2012 by the Board of Trustees of the Leland Stanford, Jr., University */ 00008 /* All Rights Reserved */ 00009 /* Produced by Andrew Hanushevsky for Stanford University under contract */ 00010 /* DE-AC02-76-SFO0515 with the Department of Energy */ 00011 /* */ 00012 /* This file is part of the XRootD software suite. */ 00013 /* */ 00014 /* XRootD is free software: you can redistribute it and/or modify it under */ 00015 /* the terms of the GNU Lesser General Public License as published by the */ 00016 /* Free Software Foundation, either version 3 of the License, or (at your */ 00017 /* option) any later version. */ 00018 /* */ 00019 /* XRootD is distributed in the hope that it will be useful, but WITHOUT */ 00020 /* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or */ 00021 /* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public */ 00022 /* License for more details. */ 00023 /* */ 00024 /* You should have received a copy of the GNU Lesser General Public License */ 00025 /* along with XRootD in a file called COPYING.LESSER (LGPL license) and file */ 00026 /* COPYING (GPL license). If not, see <http://www.gnu.org/licenses/>. */ 00027 /* */ 00028 /* The copyright holder's institutional names and contributor's names may not */ 00029 /* be used to endorse or promote products derived from this software without */ 00030 /* specific prior written permission of the institution or contributor. */ 00031 /******************************************************************************/ 00032 00033 #include "XrdOuc/XrdOucCache.hh" 00034 00035 /* The class defined here implement a general memory cache for data from an 00036 arbitrary source (e.g. files, sockets, etc). It is based on the abstract 00037 definition of a cache. In practice, only one instance of this object needs 00038 to be created since actual instances of the cache are created using the 00039 Create() method. There can be many such instances. Each instance is 00040 associated with one or more XrdOucCacheIO objects. Use the Attach() method 00041 to create such associations. 00042 00043 Notes: 1. The minimum PageSize is 4096 (4k) and must be a power of 2. 00044 The maximum PageSize is 16MB. 00045 2. The size of the cache is forced to be a multiple PageSize and 00046 have a minimum size of PageSize * 256. 00047 3. The minimum external read size is equal to PageSize. 00048 4. Currently, only write-through caches are supported. 00049 5. The Max2Cache value avoids placing data in the cache when a read 00050 exceeds the specified value. The minimum allowed is PageSize, which 00051 is also the default. 00052 6. Structured file optimization allows pages whose bytes have been 00053 fully referenced to be discarded; effectively increasing the cache. 00054 7. A structured cache treats all files as structured. By default, the 00055 cache treats files as unstructured. You can over-ride the settings 00056 on an individual file basis when the file's I/O object is attached 00057 by passing the XrdOucCache::optFIS or XrdOucCache::optFIU option. 00058 8. Write-in caches are only supported for files attached with the 00059 XrdOucCache::optWIN setting. Otherwise, updates are handled 00060 with write-through operations. 00061 9. A cache object may be deleted. However, the deletion is delayed 00062 until all CacheIO objects attached to the cache are detached. 00063 Use isAttached() to find out if any CacheIO objects are attached. 00064 10. The default maximum attached files is set to 8192 when isServer 00065 has been specified. Otherwise, it is set at 256. 00066 11. When canPreRead is specified, the cache asynchronously handles 00067 preread requests (see XrdOucCacheIO::Preread()) using 9 threads 00068 when isServer is in effect. Otherwise, 3 threads are used. 00069 12. The max queue depth for prereads is 8. When the max is exceeded 00070 the oldest preread is discarded to make room for the newest one. 00071 13. If you specify the canPreRead option when creating the cache you 00072 can also enable automatic prereads if the algorithm is workable. 00073 Otherwise, you will need to implement your own algorithm and 00074 issue prereads manually usingthe XrdOucCacheIO::Preread() method. 00075 14. The automatic preread algorithm is (ref XrdOucCacheIO::aprParms): 00076 a) A preread operation occurs when all of the following conditions 00077 are satisfied: 00078 o The cache CanPreRead option is in effect. 00079 o The read length < 'miniRead' 00080 ||(read length < 'maxiRead' && Offset == next maxi offset) 00081 b) The preread page count is set to be readlen/pagesize and the 00082 preread occurs at the page after read_offset+readlen. The page 00083 is adjusted, as follows: 00084 o If the count is < minPages, it is set to minPages. 00085 o The count must be > 0 at this point. 00086 c) Normally, pre-read pages participate in the LRU scheme. However, 00087 if the preread was triggered using 'maxiRead' then the pages are 00088 marked for single use only. This means that the moment data is 00089 delivered from the page, the page is recycled. 00090 15. Invalid options silently force the use of the default. 00091 */ 00092 00093 class XrdOucCacheDram : public XrdOucCache 00094 { 00095 public: 00096 00097 /* Attach() must be called to obtain a new XrdOucCacheIO object that fronts an 00098 existing XrdOucCacheIO object with this memory cache. 00099 Upon success a pointer to a new XrdOucCacheIO object is returned 00100 and must be used to read and write data with the cache interposed. 00101 Upon failure, the original XrdOucCacheIO object is returned with 00102 errno set. You can continue using the object without any cache. 00103 */ 00104 virtual 00105 XrdOucCacheIO *Attach(XrdOucCacheIO *ioP, int Options=0) {return 0;} 00106 00107 /* isAttached() 00108 Returns the number of CacheIO objects attached to this cache. 00109 Hence, 0 (false) if none and true otherwise. 00110 */ 00111 virtual 00112 int isAttached() {return 0;} 00113 00114 /* Create() Creates an instance of a cache using the specified parameters. 00115 You must pass the cache parms and optionally any automatic 00116 pre-read parameters that will be used as future defaults. 00117 00118 Success: returns a pointer to a new instance of the cache. 00119 Failure: a null pointer is returned with errno set to indicate 00120 the problem. 00121 */ 00122 XrdOucCache *Create(Parms &Params, XrdOucCacheIO::aprParms *aprP=0); 00123 00124 /* The following holds statistics for the cache itself. It is updated as 00125 associated cacheIO objects are deleted and their statistics are added. 00126 */ 00127 XrdOucCacheStats Stats; 00128 00129 XrdOucCacheDram() {} 00130 virtual ~XrdOucCacheDram() {} 00131 }; 00132 #endif