xrootd
XrdOucCacheDram.hh
Go to the documentation of this file.
1 #ifndef __XRDOUCCACHEDRAM_HH__
2 #define __XRDOUCCACHEDRAM_HH__
3 /******************************************************************************/
4 /* */
5 /* X r d O u c C a c h e D r a m . h h */
6 /* */
7 /* (c) 2012 by the Board of Trustees of the Leland Stanford, Jr., University */
8 /* All Rights Reserved */
9 /* Produced by Andrew Hanushevsky for Stanford University under contract */
10 /* DE-AC02-76-SFO0515 with the Department of Energy */
11 /* */
12 /* This file is part of the XRootD software suite. */
13 /* */
14 /* XRootD is free software: you can redistribute it and/or modify it under */
15 /* the terms of the GNU Lesser General Public License as published by the */
16 /* Free Software Foundation, either version 3 of the License, or (at your */
17 /* option) any later version. */
18 /* */
19 /* XRootD is distributed in the hope that it will be useful, but WITHOUT */
20 /* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or */
21 /* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public */
22 /* License for more details. */
23 /* */
24 /* You should have received a copy of the GNU Lesser General Public License */
25 /* along with XRootD in a file called COPYING.LESSER (LGPL license) and file */
26 /* COPYING (GPL license). If not, see <http://www.gnu.org/licenses/>. */
27 /* */
28 /* The copyright holder's institutional names and contributor's names may not */
29 /* be used to endorse or promote products derived from this software without */
30 /* specific prior written permission of the institution or contributor. */
31 /******************************************************************************/
32 
33 #include "XrdOuc/XrdOucCache.hh"
34 
35 /* The class defined here implement a general memory cache for data from an
36  arbitrary source (e.g. files, sockets, etc). It is based on the abstract
37  definition of a cache. In practice, only one instance of this object needs
38  to be created since actual instances of the cache are created using the
39  Create() method. There can be many such instances. Each instance is
40  associated with one or more XrdOucCacheIO objects. Use the Attach() method
41  to create such associations.
42 
43  Notes: 1. The minimum PageSize is 4096 (4k) and must be a power of 2.
44  The maximum PageSize is 16MB.
45  2. The size of the cache is forced to be a multiple PageSize and
46  have a minimum size of PageSize * 256.
47  3. The minimum external read size is equal to PageSize.
48  4. Currently, only write-through caches are supported.
49  5. The Max2Cache value avoids placing data in the cache when a read
50  exceeds the specified value. The minimum allowed is PageSize, which
51  is also the default.
52  6. Structured file optimization allows pages whose bytes have been
53  fully referenced to be discarded; effectively increasing the cache.
54  7. A structured cache treats all files as structured. By default, the
55  cache treats files as unstructured. You can over-ride the settings
56  on an individual file basis when the file's I/O object is attached
57  by passing the XrdOucCache::optFIS or XrdOucCache::optFIU option.
58  8. Write-in caches are only supported for files attached with the
59  XrdOucCache::optWIN setting. Otherwise, updates are handled
60  with write-through operations.
61  9. A cache object may be deleted. However, the deletion is delayed
62  until all CacheIO objects attached to the cache are detached.
63  Use isAttached() to find out if any CacheIO objects are attached.
64  10. The default maximum attached files is set to 8192 when isServer
65  has been specified. Otherwise, it is set at 256.
66  11. When canPreRead is specified, the cache asynchronously handles
67  preread requests (see XrdOucCacheIO::Preread()) using 9 threads
68  when isServer is in effect. Otherwise, 3 threads are used.
69  12. The max queue depth for prereads is 8. When the max is exceeded
70  the oldest preread is discarded to make room for the newest one.
71  13. If you specify the canPreRead option when creating the cache you
72  can also enable automatic prereads if the algorithm is workable.
73  Otherwise, you will need to implement your own algorithm and
74  issue prereads manually usingthe XrdOucCacheIO::Preread() method.
75  14. The automatic preread algorithm is (ref XrdOucCacheIO::aprParms):
76  a) A preread operation occurs when all of the following conditions
77  are satisfied:
78  o The cache CanPreRead option is in effect.
79  o The read length < 'miniRead'
80  ||(read length < 'maxiRead' && Offset == next maxi offset)
81  b) The preread page count is set to be readlen/pagesize and the
82  preread occurs at the page after read_offset+readlen. The page
83  is adjusted, as follows:
84  o If the count is < minPages, it is set to minPages.
85  o The count must be > 0 at this point.
86  c) Normally, pre-read pages participate in the LRU scheme. However,
87  if the preread was triggered using 'maxiRead' then the pages are
88  marked for single use only. This means that the moment data is
89  delivered from the page, the page is recycled.
90  15. Invalid options silently force the use of the default.
91 */
92 
93 class XrdOucCacheDram : public XrdOucCache
94 {
95 public:
96 
97 /* Attach() must be called to obtain a new XrdOucCacheIO object that fronts an
98  existing XrdOucCacheIO object with this memory cache.
99  Upon success a pointer to a new XrdOucCacheIO object is returned
100  and must be used to read and write data with the cache interposed.
101  Upon failure, the original XrdOucCacheIO object is returned with
102  errno set. You can continue using the object without any cache.
103 */
104 virtual
105 XrdOucCacheIO *Attach(XrdOucCacheIO *ioP, int Options=0) {return 0;}
106 
107 /* isAttached()
108  Returns the number of CacheIO objects attached to this cache.
109  Hence, 0 (false) if none and true otherwise.
110 */
111 virtual
112 int isAttached() {return 0;}
113 
114 /* Create() Creates an instance of a cache using the specified parameters.
115  You must pass the cache parms and optionally any automatic
116  pre-read parameters that will be used as future defaults.
117 
118  Success: returns a pointer to a new instance of the cache.
119  Failure: a null pointer is returned with errno set to indicate
120  the problem.
121 */
122 XrdOucCache *Create(Parms &Params, XrdOucCacheIO::aprParms *aprP=0);
123 
124 /* The following holds statistics for the cache itself. It is updated as
125  associated cacheIO objects are deleted and their statistics are added.
126 */
127 XrdOucCacheStats Stats;
128 
129  XrdOucCacheDram() {}
130 virtual ~XrdOucCacheDram() {}
131 };
132 #endif
Generated by   doxygen 1.8.3.1