Main Page | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members | Related Pages

ICache.d

Go to the documentation of this file.
00001 /*******************************************************************************
00002 
00003         @file ICache.d
00004         
00005         Copyright (C) 2004 Kris Bell
00006         
00007         This software is provided 'as-is', without any express or implied
00008         warranty. In no event will the authors be held liable for damages
00009         of any kind arising from the use of this software.
00010         
00011         Permission is hereby granted to anyone to use this software for any 
00012         purpose, including commercial applications, and to alter it and/or 
00013         redistribute it freely, subject to the following restrictions:
00014         
00015         1. The origin of this software must not be misrepresented; you must 
00016            not claim that you wrote the original software. If you use this 
00017            software in a product, an acknowledgment within documentation of 
00018            said product would be appreciated but is not required.
00019 
00020         2. Altered source versions must be plainly marked as such, and must 
00021            not be misrepresented as being the original software.
00022 
00023         3. This notice may not be removed or altered from any distribution
00024            of the source.
00025 
00026 
00027                         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
00028 
00029         
00030         @version        Initial version, April 2004      
00031         @author         Kris
00032 
00033 
00034 *******************************************************************************/
00035 
00036 module mango.cache.model.ICache;
00037 
00038 private import mango.cache.model.IPayload;
00039 
00040 /******************************************************************************
00041 
00042         Defines what a cache instance exposes. We try to keep the basic
00043         operations to a reasonable minimum.
00044 
00045 ******************************************************************************/
00046 
00047 interface ICache
00048 {
00049         /**********************************************************************
00050 
00051                 Get the cache entry identified by the given key
00052 
00053         **********************************************************************/
00054 
00055         IPayload get (char[] key);
00056 }
00057 
00058 
00059 /******************************************************************************
00060 
00061         Defines what a modifiable cache instance exposes
00062 
00063 ******************************************************************************/
00064 
00065 interface IMutableCache : ICache
00066 {
00067         /**********************************************************************
00068 
00069                 Place an entry into the cache and associate it with the
00070                 provided key. Note that there can be only one entry for
00071                 any particular key. If two keys entries are added with
00072                 the same key, the second effectively overwrites the first.
00073 
00074                 Returns what it was given
00075 
00076         **********************************************************************/
00077 
00078         IPayload put (char[] key, IPayload entry);
00079 
00080         /**********************************************************************
00081 
00082                 Remove (and return) the cache entry associated with the 
00083                 provided key. The entry will not be removed if it's time
00084                 attribute is newer than the (optional) specified 'timelimit'. 
00085 
00086                 Returns null if there is no such entry. 
00087 
00088         **********************************************************************/
00089 
00090         IPayload extract (char[] key, ulong timeLimit = ulong.max);
00091 
00092         /**********************************************************************
00093 
00094                 This is a factory for producing an ICache instance upon
00095                 the cache content. The provided loader will populate the
00096                 cache whenever a stale or missing entry is seen
00097 
00098         **********************************************************************/
00099 
00100         ICache bind (ICacheLoader loader);
00101 }
00102 
00103 
00104 /******************************************************************************
00105 
00106         Manages the lifespan of an ICache entry. These loaders effectively
00107         isolate the cache from whence the content is derived. It's a good
00108         idea to employ this abstraction where appropriate, since it allows
00109         the cache source to change with minimal (if any) impact on client
00110         code.
00111 
00112 ******************************************************************************/
00113 
00114 interface ICacheLoader
00115 {
00116         /**********************************************************************
00117 
00118                 Test the cache entry to see if it is still valid. A true
00119                 return value indicates the entry is valid, whereas false
00120                 flags the entry as stale. The latter case will cause the
00121                 load() method to be invoked.
00122 
00123         **********************************************************************/
00124 
00125         bool test (IPayload p);
00126 
00127         /**********************************************************************
00128 
00129                 Load a cache entry from wherever the content is persisted.
00130                 The 'time' argument represents that belonging to a stale
00131                 entry, which can be used to optimize the loader operation
00132                 (no need to perform a full load where there's already a 
00133                 newer version in an L2 cache). This 'time' value will be
00134                 long.min where was no such stale entry.
00135 
00136         **********************************************************************/
00137 
00138         IPayload load (char[] key, long time);
00139 }
00140 
00141 
00142 /******************************************************************************
00143 
00144         Manages the loading of ICache entries remotely, on the device
00145         that actually contains the remote cache entry. The benefit of
00146         this approach lies in the ability to 'gate' access to specific
00147         resources across the entire network. That is; where particular
00148         entries are prohibitively costly to construct, it's worthwhile
00149         ensuring that cost is reduced to a bare minimum. These remote
00150         loaders allow the cache host to block multiple network clients
00151         until there's a new entry available. Without this mechanism, 
00152         it's possible for multiple network clients to request the same
00153         entry simultaneously; therefore increasing the overall cost. 
00154         The end result is similar to that of a distributed-transaction.
00155          
00156 ******************************************************************************/
00157 
00158 interface IRemoteCacheLoader : IPayload, ICacheLoader
00159 {
00160         /**********************************************************************
00161         
00162                 Return the sleep duration between attempts to retrieve 
00163                 a locked cache entry. Consider setting this duration to
00164                 be approximately half the time you'd expect each remote 
00165                 cache-load to typically consume. The 'wait' argument is
00166                 a representation of how many microseconds have added up
00167                 while waiting. When this value exceeds some limit, you
00168                 should return zero to indicate a timeout condition.
00169 
00170                 Note that the return value should be in microseconds ~  
00171                 one tenth of a second equals 100_000 microseconds. Note
00172                 also that you might consider returning a sliding value,
00173                 where the pause starts off small, and increases as time
00174                 passes. A simple implementation might look like this:
00175 
00176                 @code
00177                 return (wait > 2_000_000) ? 0 : 10_000 + wait / 2;
00178                 @endcode
00179 
00180         **********************************************************************/
00181 
00182         uint pause (uint wait);
00183 }
00184 

Generated on Sun Nov 7 19:06:52 2004 for Mango by doxygen 1.3.6