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 
13 #include "XrdOuc/XrdOucCache.hh"
14 
15 /* The class defined here implement a general memory cache for data from an
16  arbitrary source (e.g. files, sockets, etc). It is based on the abstract
17  definition of a cache. In practice, only one instance of this object needs
18  to be created since actual instances of the cache are created using the
19  Create() method. There can be many such instances. Each instance is
20  associated with one or more XrdOucCacheIO objects. Use the Attach() method
21  to create such associations.
22 
23  Notes: 1. The minimum PageSize is 4096 (4k) and must be a power of 2.
24  The maximum PageSize is 16MB.
25  2. The size of the cache is forced to be a multiple PageSize and
26  have a minimum size of PageSize * 256.
27  3. The minimum external read size is equal to PageSize.
28  4. Currently, only write-through caches are supported.
29  5. The Max2Cache value avoids placing data in the cache when a read
30  exceeds the specified value. The minimum allowed is PageSize, which
31  is also the default.
32  6. Structured file optimization allows pages whose bytes have been
33  fully referenced to be discarded; effectively increasing the cache.
34  7. A structured cache treats all files as structured. By default, the
35  cache treats files as unstructured. You can over-ride the settings
36  on an individual file basis when the file's I/O object is attached
37  by passing the XrdOucCache::optFIS or XrdOucCache::optFIU option.
38  8. Write-in caches are only supported for files attached with the
39  XrdOucCache::optWIN setting. Otherwise, updates are handled
40  with write-through operations.
41  9. A cache object may be deleted. However, the deletion is delayed
42  until all CacheIO objects attached to the cache are detached.
43  Use isAttached() to find out if any CacheIO objects are attached.
44  10. The default maximum attached files is set to 8192 when isServer
45  has been specified. Otherwise, it is set at 256.
46  11. When canPreRead is specified, the cache asynchronously handles
47  preread requests (see XrdOucCacheIO::Preread()) using 9 threads
48  when isServer is in effect. Otherwise, 3 threads are used.
49  12. The max queue depth for prereads is 8. When the max is exceeded
50  the oldest preread is discarded to make room for the newest one.
51  13. If you specify the canPreRead option when creating the cache you
52  can also enable automatic prereads if the algorithm is workable.
53  Otherwise, you will need to implement your own algorithm and
54  issue prereads manually usingthe XrdOucCacheIO::Preread() method.
55  14. The automatic preread algorithm is (ref XrdOucCacheIO::aprParms):
56  a) A preread operation occurs when all of the following conditions
57  are satisfied:
58  o The cache CanPreRead option is in effect.
59  o The read length < 'miniRead'
60  ||(read length < 'maxiRead' && Offset == next maxi offset)
61  b) The preread page count is set to be readlen/pagesize and the
62  preread occurs at the page after read_offset+readlen. The page
63  is adjusted, as follows:
64  o If the count is < minPages, it is set to minPages.
65  o The count must be > 0 at this point.
66  c) Normally, pre-read pages participate in the LRU scheme. However,
67  if the preread was triggered using 'maxiRead' then the pages are
68  marked for single use only. This means that the moment data is
69  delivered from the page, the page is recycled.
70  15. Invalid options silently force the use of the default.
71 */
72 
73 class XrdOucCacheDram : public XrdOucCache
74 {
75 public:
76 
77 /* Attach() must be called to obtain a new XrdOucCacheIO object that fronts an
78  existing XrdOucCacheIO object with this memory cache.
79  Upon success a pointer to a new XrdOucCacheIO object is returned
80  and must be used to read and write data with the cache interposed.
81  Upon failure, the original XrdOucCacheIO object is returned with
82  errno set. You can continue using the object without any cache.
83 */
84 virtual
85 XrdOucCacheIO *Attach(XrdOucCacheIO *ioP, int Options=0) {return 0;}
86 
87 /* isAttached()
88  Returns the number of CacheIO objects attached to this cache.
89  Hence, 0 (false) if none and true otherwise.
90 */
91 virtual
92 int isAttached() {return 0;}
93 
94 /* Create() Creates an instance of a cache using the specified parameters.
95  You must pass the cache parms and optionally any automatic
96  pre-read parameters that will be used as future defaults.
97 
98  Success: returns a pointer to a new instance of the cache.
99  Failure: a null pointer is returned with errno set to indicate
100  the problem.
101 */
102 XrdOucCache *Create(Parms &Params, XrdOucCacheIO::aprParms *aprP=0);
103 
104 /* The following holds statistics for the cache itself. It is updated as
105  associated cacheIO objects are deleted and their statistics are added.
106 */
107 XrdOucCacheStats Stats;
108 
109  XrdOucCacheDram() {}
110 virtual ~XrdOucCacheDram() {}
111 };
112 #endif
Generated by   doxygen 1.8.1.2