aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/OpenSim/Framework/ICnmCache.cs
diff options
context:
space:
mode:
Diffstat (limited to 'OpenSim/Framework/ICnmCache.cs')
-rw-r--r--OpenSim/Framework/ICnmCache.cs882
1 files changed, 441 insertions, 441 deletions
diff --git a/OpenSim/Framework/ICnmCache.cs b/OpenSim/Framework/ICnmCache.cs
index cba8a7f..2f62189 100644
--- a/OpenSim/Framework/ICnmCache.cs
+++ b/OpenSim/Framework/ICnmCache.cs
@@ -1,441 +1,441 @@
1/* 1/*
2 * Copyright (c) Contributors, http://opensimulator.org/ 2 * Copyright (c) Contributors, http://opensimulator.org/
3 * See CONTRIBUTORS.TXT for a full list of copyright holders. 3 * See CONTRIBUTORS.TXT for a full list of copyright holders.
4 * 4 *
5 * Redistribution and use in source and binary forms, with or without 5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met: 6 * modification, are permitted provided that the following conditions are met:
7 * * Redistributions of source code must retain the above copyright 7 * * Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer. 8 * notice, this list of conditions and the following disclaimer.
9 * * Redistributions in binary form must reproduce the above copyright 9 * * Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the 10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution. 11 * documentation and/or other materials provided with the distribution.
12 * * Neither the name of the OpenSimulator Project nor the 12 * * Neither the name of the OpenSimulator Project nor the
13 * names of its contributors may be used to endorse or promote products 13 * names of its contributors may be used to endorse or promote products
14 * derived from this software without specific prior written permission. 14 * derived from this software without specific prior written permission.
15 * 15 *
16 * THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY 16 * THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY
17 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 17 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 18 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19 * DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY 19 * DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY
20 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 20 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 21 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 22 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */ 26 */
27 27
28using System; 28using System;
29using System.Collections.Generic; 29using System.Collections.Generic;
30 30
31namespace OpenSim.Framework 31namespace OpenSim.Framework
32{ 32{
33 /// <summary> 33 /// <summary>
34 /// Represent generic cache to store key/value pairs (elements) limited by time, size and count of elements. 34 /// Represent generic cache to store key/value pairs (elements) limited by time, size and count of elements.
35 /// </summary> 35 /// </summary>
36 /// <typeparam name="TKey"> 36 /// <typeparam name="TKey">
37 /// The type of keys in the cache. 37 /// The type of keys in the cache.
38 /// </typeparam> 38 /// </typeparam>
39 /// <typeparam name="TValue"> 39 /// <typeparam name="TValue">
40 /// The type of values in the cache. 40 /// The type of values in the cache.
41 /// </typeparam> 41 /// </typeparam>
42 /// <remarks> 42 /// <remarks>
43 /// <para> 43 /// <para>
44 /// Cache store limitations: 44 /// Cache store limitations:
45 /// </para> 45 /// </para>
46 /// <list type="table"> 46 /// <list type="table">
47 /// <listheader> 47 /// <listheader>
48 /// <term>Limitation</term> 48 /// <term>Limitation</term>
49 /// <description>Description</description> 49 /// <description>Description</description>
50 /// </listheader> 50 /// </listheader>
51 /// <item> 51 /// <item>
52 /// <term>Time</term> 52 /// <term>Time</term>
53 /// <description> 53 /// <description>
54 /// Element that is not accessed through <see cref="TryGetValue"/> or <see cref="Set"/> in last <see cref="ExpirationTime"/> are 54 /// Element that is not accessed through <see cref="TryGetValue"/> or <see cref="Set"/> in last <see cref="ExpirationTime"/> are
55 /// removed from the cache automatically. Depending on implementation of the cache some of elements may stay longer in cache. 55 /// removed from the cache automatically. Depending on implementation of the cache some of elements may stay longer in cache.
56 /// <see cref="IsTimeLimited"/> returns <see langword="true"/>, if cache is limited by time. 56 /// <see cref="IsTimeLimited"/> returns <see langword="true"/>, if cache is limited by time.
57 /// </description> 57 /// </description>
58 /// </item> 58 /// </item>
59 /// <item> 59 /// <item>
60 /// <term>Count</term> 60 /// <term>Count</term>
61 /// <description> 61 /// <description>
62 /// When adding an new element to cache that already have <see cref="MaxCount"/> of elements, cache will remove less recently 62 /// When adding an new element to cache that already have <see cref="MaxCount"/> of elements, cache will remove less recently
63 /// used element(s) from the cache, until element fits to cache. 63 /// used element(s) from the cache, until element fits to cache.
64 /// <see cref="IsCountLimited"/> returns <see langword="true"/>, if cache is limiting element count. 64 /// <see cref="IsCountLimited"/> returns <see langword="true"/>, if cache is limiting element count.
65 /// </description> 65 /// </description>
66 /// </item> 66 /// </item>
67 /// <item> 67 /// <item>
68 /// <term>Size</term> 68 /// <term>Size</term>
69 /// <description> 69 /// <description>
70 /// <description> 70 /// <description>
71 /// When adding an new element to cache that already have <see cref="MaxSize"/> of elements, cache will remove less recently 71 /// When adding an new element to cache that already have <see cref="MaxSize"/> of elements, cache will remove less recently
72 /// used element(s) from the cache, until element fits to cache. 72 /// used element(s) from the cache, until element fits to cache.
73 /// <see cref="IsSizeLimited"/> returns <see langword="true"/>, if cache is limiting total size of elements. 73 /// <see cref="IsSizeLimited"/> returns <see langword="true"/>, if cache is limiting total size of elements.
74 /// Normally size is bytes used by element in the cache. But it can be any other suitable unit of measure. 74 /// Normally size is bytes used by element in the cache. But it can be any other suitable unit of measure.
75 /// </description> 75 /// </description>
76 /// </description> 76 /// </description>
77 /// </item> 77 /// </item>
78 /// </list> 78 /// </list>
79 /// </remarks> 79 /// </remarks>
80 public interface ICnmCache<TKey, TValue> : IEnumerable<KeyValuePair<TKey, TValue>> 80 public interface ICnmCache<TKey, TValue> : IEnumerable<KeyValuePair<TKey, TValue>>
81 { 81 {
82 /// <summary> 82 /// <summary>
83 /// Gets current count of elements stored to <see cref="ICnmCache{TKey,TValue}"/>. 83 /// Gets current count of elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
84 /// </summary> 84 /// </summary>
85 /// <remarks> 85 /// <remarks>
86 /// <para> 86 /// <para>
87 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count, 87 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count,
88 /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element. 88 /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element.
89 /// </para> 89 /// </para>
90 /// </remarks> 90 /// </remarks>
91 /// <seealso cref="MaxCount"/> 91 /// <seealso cref="MaxCount"/>
92 /// <seealso cref="IsCountLimited"/> 92 /// <seealso cref="IsCountLimited"/>
93 /// <seealso cref="IsSizeLimited"/> 93 /// <seealso cref="IsSizeLimited"/>
94 /// <seealso cref="IsTimeLimited"/> 94 /// <seealso cref="IsTimeLimited"/>
95 int Count { get; } 95 int Count { get; }
96 96
97 /// <summary> 97 /// <summary>
98 /// Gets or sets elements expiration time. 98 /// Gets or sets elements expiration time.
99 /// </summary> 99 /// </summary>
100 /// <value> 100 /// <value>
101 /// Elements expiration time. 101 /// Elements expiration time.
102 /// </value> 102 /// </value>
103 /// <remarks> 103 /// <remarks>
104 /// <para> 104 /// <para>
105 /// When element has been stored in <see cref="ICnmCache{TKey,TValue}"/> longer than <see cref="ExpirationTime"/> 105 /// When element has been stored in <see cref="ICnmCache{TKey,TValue}"/> longer than <see cref="ExpirationTime"/>
106 /// and it is not accessed through <see cref="TryGetValue"/> method or element's value is 106 /// and it is not accessed through <see cref="TryGetValue"/> method or element's value is
107 /// not replaced by <see cref="Set"/> method, then it is automatically removed from the 107 /// not replaced by <see cref="Set"/> method, then it is automatically removed from the
108 /// <see cref="ICnmCache{TKey,TValue}"/>. 108 /// <see cref="ICnmCache{TKey,TValue}"/>.
109 /// </para> 109 /// </para>
110 /// <para> 110 /// <para>
111 /// It is possible that <see cref="ICnmCache{TKey,TValue}"/> implementation removes element before it's expiration time, 111 /// It is possible that <see cref="ICnmCache{TKey,TValue}"/> implementation removes element before it's expiration time,
112 /// because total size or count of elements stored to cache is larger than <see cref="MaxSize"/> or <see cref="MaxCount"/>. 112 /// because total size or count of elements stored to cache is larger than <see cref="MaxSize"/> or <see cref="MaxCount"/>.
113 /// </para> 113 /// </para>
114 /// <para> 114 /// <para>
115 /// It is also possible that element stays in cache longer than <see cref="ExpirationTime"/>. 115 /// It is also possible that element stays in cache longer than <see cref="ExpirationTime"/>.
116 /// </para> 116 /// </para>
117 /// <para> 117 /// <para>
118 /// Calling <see cref="PurgeExpired"/> try to remove all elements that are expired. 118 /// Calling <see cref="PurgeExpired"/> try to remove all elements that are expired.
119 /// </para> 119 /// </para>
120 /// <para> 120 /// <para>
121 /// To disable time limit in cache, set <see cref="ExpirationTime"/> to <see cref="DateTime.MaxValue"/>. 121 /// To disable time limit in cache, set <see cref="ExpirationTime"/> to <see cref="DateTime.MaxValue"/>.
122 /// </para> 122 /// </para>
123 /// </remarks> 123 /// </remarks>
124 /// <seealso cref="IsTimeLimited"/> 124 /// <seealso cref="IsTimeLimited"/>
125 /// <seealso cref="IsCountLimited"/> 125 /// <seealso cref="IsCountLimited"/>
126 /// <seealso cref="IsSizeLimited"/> 126 /// <seealso cref="IsSizeLimited"/>
127 /// <seealso cref="PurgeExpired"/> 127 /// <seealso cref="PurgeExpired"/>
128 /// <seealso cref="Count"/> 128 /// <seealso cref="Count"/>
129 /// <seealso cref="MaxCount"/> 129 /// <seealso cref="MaxCount"/>
130 /// <seealso cref="MaxSize"/> 130 /// <seealso cref="MaxSize"/>
131 /// <seealso cref="Size"/> 131 /// <seealso cref="Size"/>
132 TimeSpan ExpirationTime { get; set; } 132 TimeSpan ExpirationTime { get; set; }
133 133
134 /// <summary> 134 /// <summary>
135 /// Gets a value indicating whether or not access to the <see cref="ICnmCache{TKey,TValue}"/> is synchronized (thread safe). 135 /// Gets a value indicating whether or not access to the <see cref="ICnmCache{TKey,TValue}"/> is synchronized (thread safe).
136 /// </summary> 136 /// </summary>
137 /// <value> 137 /// <value>
138 /// <see langword="true"/> if access to the <see cref="ICnmCache{TKey,TValue}"/> is synchronized (thread safe); 138 /// <see langword="true"/> if access to the <see cref="ICnmCache{TKey,TValue}"/> is synchronized (thread safe);
139 /// otherwise, <see langword="false"/>. 139 /// otherwise, <see langword="false"/>.
140 /// </value> 140 /// </value>
141 /// <remarks> 141 /// <remarks>
142 /// <para> 142 /// <para>
143 /// To get synchronized (thread safe) access to <see cref="ICnmCache{TKey,TValue}"/> object, use 143 /// To get synchronized (thread safe) access to <see cref="ICnmCache{TKey,TValue}"/> object, use
144 /// <see cref="CnmSynchronizedCache{TKey,TValue}.Synchronized"/> in <see cref="CnmSynchronizedCache{TKey,TValue}"/> class 144 /// <see cref="CnmSynchronizedCache{TKey,TValue}.Synchronized"/> in <see cref="CnmSynchronizedCache{TKey,TValue}"/> class
145 /// to retrieve synchronized wrapper for <see cref="ICnmCache{TKey,TValue}"/> object. 145 /// to retrieve synchronized wrapper for <see cref="ICnmCache{TKey,TValue}"/> object.
146 /// </para> 146 /// </para>
147 /// </remarks> 147 /// </remarks>
148 /// <seealso cref="SyncRoot"/> 148 /// <seealso cref="SyncRoot"/>
149 /// <seealso cref="CnmSynchronizedCache{TKey,TValue}"/> 149 /// <seealso cref="CnmSynchronizedCache{TKey,TValue}"/>
150 bool IsSynchronized { get; } 150 bool IsSynchronized { get; }
151 151
152 /// <summary> 152 /// <summary>
153 /// Gets a value indicating whether <see cref="ICnmCache{TKey,TValue}"/> is limiting count of elements. 153 /// Gets a value indicating whether <see cref="ICnmCache{TKey,TValue}"/> is limiting count of elements.
154 /// </summary> 154 /// </summary>
155 /// <value> 155 /// <value>
156 /// <see langword="true"/> if the <see cref="ICnmCache{TKey,TValue}"/> count of elements is limited; 156 /// <see langword="true"/> if the <see cref="ICnmCache{TKey,TValue}"/> count of elements is limited;
157 /// otherwise, <see langword="false"/>. 157 /// otherwise, <see langword="false"/>.
158 /// </value> 158 /// </value>
159 /// <remarks> 159 /// <remarks>
160 /// <para> 160 /// <para>
161 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count, 161 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count,
162 /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element. 162 /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element.
163 /// </para> 163 /// </para>
164 /// </remarks> 164 /// </remarks>
165 /// <seealso cref="Count"/> 165 /// <seealso cref="Count"/>
166 /// <seealso cref="MaxCount"/> 166 /// <seealso cref="MaxCount"/>
167 /// <seealso cref="IsSizeLimited"/> 167 /// <seealso cref="IsSizeLimited"/>
168 /// <seealso cref="IsTimeLimited"/> 168 /// <seealso cref="IsTimeLimited"/>
169 bool IsCountLimited { get; } 169 bool IsCountLimited { get; }
170 170
171 /// <summary> 171 /// <summary>
172 /// Gets a value indicating whether <see cref="ICnmCache{TKey,TValue}"/> is limiting size of elements. 172 /// Gets a value indicating whether <see cref="ICnmCache{TKey,TValue}"/> is limiting size of elements.
173 /// </summary> 173 /// </summary>
174 /// <value> 174 /// <value>
175 /// <see langword="true"/> if the <see cref="ICnmCache{TKey,TValue}"/> total size of elements is limited; 175 /// <see langword="true"/> if the <see cref="ICnmCache{TKey,TValue}"/> total size of elements is limited;
176 /// otherwise, <see langword="false"/>. 176 /// otherwise, <see langword="false"/>.
177 /// </value> 177 /// </value>
178 /// <remarks> 178 /// <remarks>
179 /// <para> 179 /// <para>
180 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements, 180 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements,
181 /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element. 181 /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element.
182 /// </para> 182 /// </para>
183 /// </remarks> 183 /// </remarks>
184 /// <seealso cref="MaxElementSize"/> 184 /// <seealso cref="MaxElementSize"/>
185 /// <seealso cref="Size"/> 185 /// <seealso cref="Size"/>
186 /// <seealso cref="MaxSize"/> 186 /// <seealso cref="MaxSize"/>
187 /// <seealso cref="IsCountLimited"/> 187 /// <seealso cref="IsCountLimited"/>
188 /// <seealso cref="IsTimeLimited"/> 188 /// <seealso cref="IsTimeLimited"/>
189 bool IsSizeLimited { get; } 189 bool IsSizeLimited { get; }
190 190
191 /// <summary> 191 /// <summary>
192 /// Gets a value indicating whether elements stored to <see cref="ICnmCache{TKey,TValue}"/> have limited inactivity time. 192 /// Gets a value indicating whether elements stored to <see cref="ICnmCache{TKey,TValue}"/> have limited inactivity time.
193 /// </summary> 193 /// </summary>
194 /// <value> 194 /// <value>
195 /// <see langword="true"/> if the <see cref="ICnmCache{TKey,TValue}"/> has a fixed total size of elements; 195 /// <see langword="true"/> if the <see cref="ICnmCache{TKey,TValue}"/> has a fixed total size of elements;
196 /// otherwise, <see langword="false"/>. 196 /// otherwise, <see langword="false"/>.
197 /// </value> 197 /// </value>
198 /// <remarks> 198 /// <remarks>
199 /// If <see cref="ICnmCache{TKey,TValue}"/> have limited inactivity time and element is not accessed through <see cref="Set"/> 199 /// If <see cref="ICnmCache{TKey,TValue}"/> have limited inactivity time and element is not accessed through <see cref="Set"/>
200 /// or <see cref="TryGetValue"/> methods in <see cref="ExpirationTime"/> , then element is automatically removed from 200 /// or <see cref="TryGetValue"/> methods in <see cref="ExpirationTime"/> , then element is automatically removed from
201 /// the cache. Depending on implementation of the <see cref="ICnmCache{TKey,TValue}"/>, some of the elements may 201 /// the cache. Depending on implementation of the <see cref="ICnmCache{TKey,TValue}"/>, some of the elements may
202 /// stay longer in cache. 202 /// stay longer in cache.
203 /// </remarks> 203 /// </remarks>
204 /// <seealso cref="ExpirationTime"/> 204 /// <seealso cref="ExpirationTime"/>
205 /// <seealso cref="PurgeExpired"/> 205 /// <seealso cref="PurgeExpired"/>
206 /// <seealso cref="IsCountLimited"/> 206 /// <seealso cref="IsCountLimited"/>
207 /// <seealso cref="IsSizeLimited"/> 207 /// <seealso cref="IsSizeLimited"/>
208 bool IsTimeLimited { get; } 208 bool IsTimeLimited { get; }
209 209
210 /// <summary> 210 /// <summary>
211 /// Gets or sets maximal allowed count of elements that can be stored to <see cref="ICnmCache{TKey,TValue}"/>. 211 /// Gets or sets maximal allowed count of elements that can be stored to <see cref="ICnmCache{TKey,TValue}"/>.
212 /// </summary> 212 /// </summary>
213 /// <value> 213 /// <value>
214 /// <see cref="int.MaxValue"/>, if <see cref="ICnmCache{TKey,TValue}"/> is not limited by count of elements; 214 /// <see cref="int.MaxValue"/>, if <see cref="ICnmCache{TKey,TValue}"/> is not limited by count of elements;
215 /// otherwise maximal allowed count of elements. 215 /// otherwise maximal allowed count of elements.
216 /// </value> 216 /// </value>
217 /// <remarks> 217 /// <remarks>
218 /// <para> 218 /// <para>
219 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count, 219 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count,
220 /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element. 220 /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element.
221 /// </para> 221 /// </para>
222 /// </remarks> 222 /// </remarks>
223 int MaxCount { get; set; } 223 int MaxCount { get; set; }
224 224
225 /// <summary> 225 /// <summary>
226 /// <para>Gets maximal allowed element size.</para> 226 /// <para>Gets maximal allowed element size.</para>
227 /// </summary> 227 /// </summary>
228 /// <value> 228 /// <value>
229 /// Maximal allowed element size. 229 /// Maximal allowed element size.
230 /// </value> 230 /// </value>
231 /// <remarks> 231 /// <remarks>
232 /// <para> 232 /// <para>
233 /// If element's size is larger than <see cref="MaxElementSize"/>, then element is 233 /// If element's size is larger than <see cref="MaxElementSize"/>, then element is
234 /// not added to the <see cref="ICnmCache{TKey,TValue}"/>. 234 /// not added to the <see cref="ICnmCache{TKey,TValue}"/>.
235 /// </para> 235 /// </para>
236 /// </remarks> 236 /// </remarks>
237 /// <seealso cref="Set"/> 237 /// <seealso cref="Set"/>
238 /// <seealso cref="IsSizeLimited"/> 238 /// <seealso cref="IsSizeLimited"/>
239 /// <seealso cref="Size"/> 239 /// <seealso cref="Size"/>
240 /// <seealso cref="MaxSize"/> 240 /// <seealso cref="MaxSize"/>
241 long MaxElementSize { get; } 241 long MaxElementSize { get; }
242 242
243 /// <summary> 243 /// <summary>
244 /// Gets or sets maximal allowed total size for elements stored to <see cref="ICnmCache{TKey,TValue}"/>. 244 /// Gets or sets maximal allowed total size for elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
245 /// </summary> 245 /// </summary>
246 /// <value> 246 /// <value>
247 /// Maximal allowed total size for elements stored to <see cref="ICnmCache{TKey,TValue}"/>. 247 /// Maximal allowed total size for elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
248 /// </value> 248 /// </value>
249 /// <remarks> 249 /// <remarks>
250 /// <para> 250 /// <para>
251 /// Normally size is total bytes used by elements in the cache. But it can be any other suitable unit of measure. 251 /// Normally size is total bytes used by elements in the cache. But it can be any other suitable unit of measure.
252 /// </para> 252 /// </para>
253 /// <para> 253 /// <para>
254 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements, 254 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements,
255 /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element. 255 /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element.
256 /// </para> 256 /// </para>
257 /// </remarks> 257 /// </remarks>
258 /// <exception cref="ArgumentOutOfRangeException">value is less than 0.</exception> 258 /// <exception cref="ArgumentOutOfRangeException">value is less than 0.</exception>
259 /// <seealso cref="MaxElementSize"/> 259 /// <seealso cref="MaxElementSize"/>
260 /// <seealso cref="IsSizeLimited"/> 260 /// <seealso cref="IsSizeLimited"/>
261 /// <seealso cref="Size"/> 261 /// <seealso cref="Size"/>
262 long MaxSize { get; set; } 262 long MaxSize { get; set; }
263 263
264 /// <summary> 264 /// <summary>
265 /// Gets total size of elements stored to <see cref="ICnmCache{TKey,TValue}"/>. 265 /// Gets total size of elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
266 /// </summary> 266 /// </summary>
267 /// <value> 267 /// <value>
268 /// Total size of elements stored to <see cref="ICnmCache{TKey,TValue}"/>. 268 /// Total size of elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
269 /// </value> 269 /// </value>
270 /// <remarks> 270 /// <remarks>
271 /// <para> 271 /// <para>
272 /// Normally bytes, but can be any suitable unit of measure. 272 /// Normally bytes, but can be any suitable unit of measure.
273 /// </para> 273 /// </para>
274 /// <para> 274 /// <para>
275 /// Element's size is given when element is added or replaced by <see cref="Set"/> method. 275 /// Element's size is given when element is added or replaced by <see cref="Set"/> method.
276 /// </para> 276 /// </para>
277 /// <para> 277 /// <para>
278 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements, 278 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements,
279 /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element. 279 /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element.
280 /// </para> 280 /// </para>
281 /// </remarks> 281 /// </remarks>
282 /// <seealso cref="MaxElementSize"/> 282 /// <seealso cref="MaxElementSize"/>
283 /// <seealso cref="IsSizeLimited"/> 283 /// <seealso cref="IsSizeLimited"/>
284 /// <seealso cref="MaxSize"/> 284 /// <seealso cref="MaxSize"/>
285 /// <seealso cref="IsCountLimited"/> 285 /// <seealso cref="IsCountLimited"/>
286 /// <seealso cref="ExpirationTime"/> 286 /// <seealso cref="ExpirationTime"/>
287 long Size { get; } 287 long Size { get; }
288 288
289 /// <summary> 289 /// <summary>
290 /// Gets an object that can be used to synchronize access to the <see cref="ICnmCache{TKey,TValue}"/>. 290 /// Gets an object that can be used to synchronize access to the <see cref="ICnmCache{TKey,TValue}"/>.
291 /// </summary> 291 /// </summary>
292 /// <value> 292 /// <value>
293 /// An object that can be used to synchronize access to the <see cref="ICnmCache{TKey,TValue}"/>. 293 /// An object that can be used to synchronize access to the <see cref="ICnmCache{TKey,TValue}"/>.
294 /// </value> 294 /// </value>
295 /// <remarks> 295 /// <remarks>
296 /// <para> 296 /// <para>
297 /// To get synchronized (thread safe) access to <see cref="ICnmCache{TKey,TValue}"/>, use <see cref="CnmSynchronizedCache{TKey,TValue}"/> 297 /// To get synchronized (thread safe) access to <see cref="ICnmCache{TKey,TValue}"/>, use <see cref="CnmSynchronizedCache{TKey,TValue}"/>
298 /// method <see cref="CnmSynchronizedCache{TKey,TValue}.Synchronized"/> to retrieve synchronized wrapper interface to 298 /// method <see cref="CnmSynchronizedCache{TKey,TValue}.Synchronized"/> to retrieve synchronized wrapper interface to
299 /// <see cref="ICnmCache{TKey,TValue}"/>. 299 /// <see cref="ICnmCache{TKey,TValue}"/>.
300 /// </para> 300 /// </para>
301 /// </remarks> 301 /// </remarks>
302 /// <seealso cref="IsSynchronized"/> 302 /// <seealso cref="IsSynchronized"/>
303 /// <seealso cref="CnmSynchronizedCache{TKey,TValue}"/> 303 /// <seealso cref="CnmSynchronizedCache{TKey,TValue}"/>
304 object SyncRoot { get; } 304 object SyncRoot { get; }
305 305
306 /// <summary> 306 /// <summary>
307 /// Removes all elements from the <see cref="ICnmCache{TKey,TValue}"/>. 307 /// Removes all elements from the <see cref="ICnmCache{TKey,TValue}"/>.
308 /// </summary> 308 /// </summary>
309 /// <seealso cref="Set"/> 309 /// <seealso cref="Set"/>
310 /// <seealso cref="Remove"/> 310 /// <seealso cref="Remove"/>
311 /// <seealso cref="RemoveRange"/> 311 /// <seealso cref="RemoveRange"/>
312 /// <seealso cref="TryGetValue"/> 312 /// <seealso cref="TryGetValue"/>
313 /// <seealso cref="PurgeExpired"/> 313 /// <seealso cref="PurgeExpired"/>
314 void Clear(); 314 void Clear();
315 315
316 /// <summary> 316 /// <summary>
317 /// Purge expired elements from the <see cref="ICnmCache{TKey,TValue}"/>. 317 /// Purge expired elements from the <see cref="ICnmCache{TKey,TValue}"/>.
318 /// </summary> 318 /// </summary>
319 /// <remarks> 319 /// <remarks>
320 /// <para> 320 /// <para>
321 /// Element becomes expired when last access time to it has been longer time than <see cref="ExpirationTime"/>. 321 /// Element becomes expired when last access time to it has been longer time than <see cref="ExpirationTime"/>.
322 /// </para> 322 /// </para>
323 /// <para> 323 /// <para>
324 /// Depending on <see cref="ICnmCache{TKey,TValue}"/> implementation, some of expired elements 324 /// Depending on <see cref="ICnmCache{TKey,TValue}"/> implementation, some of expired elements
325 /// may stay longer than <see cref="ExpirationTime"/> in the cache. 325 /// may stay longer than <see cref="ExpirationTime"/> in the cache.
326 /// </para> 326 /// </para>
327 /// </remarks> 327 /// </remarks>
328 /// <seealso cref="IsTimeLimited"/> 328 /// <seealso cref="IsTimeLimited"/>
329 /// <seealso cref="ExpirationTime"/> 329 /// <seealso cref="ExpirationTime"/>
330 /// <seealso cref="Set"/> 330 /// <seealso cref="Set"/>
331 /// <seealso cref="Remove"/> 331 /// <seealso cref="Remove"/>
332 /// <seealso cref="RemoveRange"/> 332 /// <seealso cref="RemoveRange"/>
333 /// <seealso cref="TryGetValue"/> 333 /// <seealso cref="TryGetValue"/>
334 /// <seealso cref="Clear"/> 334 /// <seealso cref="Clear"/>
335 void PurgeExpired(); 335 void PurgeExpired();
336 336
337 /// <summary> 337 /// <summary>
338 /// Removes element associated with <paramref name="key"/> from the <see cref="ICnmCache{TKey,TValue}"/>. 338 /// Removes element associated with <paramref name="key"/> from the <see cref="ICnmCache{TKey,TValue}"/>.
339 /// </summary> 339 /// </summary>
340 /// <param name="key"> 340 /// <param name="key">
341 /// The key that is associated with element to remove from the <see cref="ICnmCache{TKey,TValue}"/>. 341 /// The key that is associated with element to remove from the <see cref="ICnmCache{TKey,TValue}"/>.
342 /// </param> 342 /// </param>
343 /// <exception cref="ArgumentNullException"> 343 /// <exception cref="ArgumentNullException">
344 /// <paramref name="key"/> is <see langword="null"/>. 344 /// <paramref name="key"/> is <see langword="null"/>.
345 /// </exception> 345 /// </exception>
346 /// <seealso cref="Set"/> 346 /// <seealso cref="Set"/>
347 /// <seealso cref="RemoveRange"/> 347 /// <seealso cref="RemoveRange"/>
348 /// <seealso cref="TryGetValue"/> 348 /// <seealso cref="TryGetValue"/>
349 /// <seealso cref="Clear"/> 349 /// <seealso cref="Clear"/>
350 /// <seealso cref="PurgeExpired"/> 350 /// <seealso cref="PurgeExpired"/>
351 void Remove( TKey key ); 351 void Remove( TKey key );
352 352
353 /// <summary> 353 /// <summary>
354 /// Removes elements that are associated with one of <paramref name="keys"/> from the <see cref="ICnmCache{TKey,TValue}"/>. 354 /// Removes elements that are associated with one of <paramref name="keys"/> from the <see cref="ICnmCache{TKey,TValue}"/>.
355 /// </summary> 355 /// </summary>
356 /// <param name="keys"> 356 /// <param name="keys">
357 /// The keys that are associated with elements to remove from the <see cref="ICnmCache{TKey,TValue}"/>. 357 /// The keys that are associated with elements to remove from the <see cref="ICnmCache{TKey,TValue}"/>.
358 /// </param> 358 /// </param>
359 /// <exception cref="ArgumentNullException"> 359 /// <exception cref="ArgumentNullException">
360 /// <paramref name="keys"/> is <see langword="null"/>. 360 /// <paramref name="keys"/> is <see langword="null"/>.
361 /// </exception> 361 /// </exception>
362 /// <seealso cref="Set"/> 362 /// <seealso cref="Set"/>
363 /// <seealso cref="Remove"/> 363 /// <seealso cref="Remove"/>
364 /// <seealso cref="TryGetValue"/> 364 /// <seealso cref="TryGetValue"/>
365 /// <seealso cref="Clear"/> 365 /// <seealso cref="Clear"/>
366 /// <seealso cref="PurgeExpired"/> 366 /// <seealso cref="PurgeExpired"/>
367 void RemoveRange( IEnumerable<TKey> keys ); 367 void RemoveRange( IEnumerable<TKey> keys );
368 368
369 /// <summary> 369 /// <summary>
370 /// Add or replace an element with the provided <paramref name="key"/>, <paramref name="value"/> and <paramref name="size"/> to 370 /// Add or replace an element with the provided <paramref name="key"/>, <paramref name="value"/> and <paramref name="size"/> to
371 /// <see cref="ICnmCache{TKey,TValue}"/>. 371 /// <see cref="ICnmCache{TKey,TValue}"/>.
372 /// </summary> 372 /// </summary>
373 /// <param name="key"> 373 /// <param name="key">
374 /// The object used as the key of the element. Can't be <see langword="null"/> reference. 374 /// The object used as the key of the element. Can't be <see langword="null"/> reference.
375 /// </param> 375 /// </param>
376 /// <param name="value"> 376 /// <param name="value">
377 /// The object used as the value of the element to add or replace. <see langword="null"/> is allowed. 377 /// The object used as the value of the element to add or replace. <see langword="null"/> is allowed.
378 /// </param> 378 /// </param>
379 /// <param name="size"> 379 /// <param name="size">
380 /// The element's size. Normally bytes, but can be any suitable unit of measure. 380 /// The element's size. Normally bytes, but can be any suitable unit of measure.
381 /// </param> 381 /// </param>
382 /// <returns> 382 /// <returns>
383 /// <see langword="true"/> if element has been added successfully to the <see cref="ICnmCache{TKey,TValue}"/>; 383 /// <see langword="true"/> if element has been added successfully to the <see cref="ICnmCache{TKey,TValue}"/>;
384 /// otherwise <see langword="false"/>. 384 /// otherwise <see langword="false"/>.
385 /// </returns> 385 /// </returns>
386 /// <exception cref="ArgumentNullException"> 386 /// <exception cref="ArgumentNullException">
387 /// <paramref name="key"/>is <see langword="null"/>. 387 /// <paramref name="key"/>is <see langword="null"/>.
388 /// </exception> 388 /// </exception>
389 /// <exception cref="ArgumentOutOfRangeException"> 389 /// <exception cref="ArgumentOutOfRangeException">
390 /// The element's <paramref name="size"/> is less than 0. 390 /// The element's <paramref name="size"/> is less than 0.
391 /// </exception> 391 /// </exception>
392 /// <remarks> 392 /// <remarks>
393 /// <para> 393 /// <para>
394 /// If element's <paramref name="size"/> is larger than <see cref="MaxElementSize"/>, then element is 394 /// If element's <paramref name="size"/> is larger than <see cref="MaxElementSize"/>, then element is
395 /// not added to the <see cref="ICnmCache{TKey,TValue}"/>, however - possible older element is 395 /// not added to the <see cref="ICnmCache{TKey,TValue}"/>, however - possible older element is
396 /// removed from the <see cref="ICnmCache{TKey,TValue}"/>. 396 /// removed from the <see cref="ICnmCache{TKey,TValue}"/>.
397 /// </para> 397 /// </para>
398 /// <para> 398 /// <para>
399 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements, 399 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements,
400 /// <see cref="ICnmCache{TKey,TValue}"/>will remove less recently used elements until it can fit an new element. 400 /// <see cref="ICnmCache{TKey,TValue}"/>will remove less recently used elements until it can fit an new element.
401 /// </para> 401 /// </para>
402 /// <para> 402 /// <para>
403 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count, 403 /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count,
404 /// <see cref="ICnmCache{TKey,TValue}"/>will remove less recently used elements until it can fit an new element. 404 /// <see cref="ICnmCache{TKey,TValue}"/>will remove less recently used elements until it can fit an new element.
405 /// </para> 405 /// </para>
406 /// </remarks> 406 /// </remarks>
407 /// <seealso cref="IsSizeLimited"/> 407 /// <seealso cref="IsSizeLimited"/>
408 /// <seealso cref="IsCountLimited"/> 408 /// <seealso cref="IsCountLimited"/>
409 /// <seealso cref="Remove"/> 409 /// <seealso cref="Remove"/>
410 /// <seealso cref="RemoveRange"/> 410 /// <seealso cref="RemoveRange"/>
411 /// <seealso cref="TryGetValue"/> 411 /// <seealso cref="TryGetValue"/>
412 /// <seealso cref="Clear"/> 412 /// <seealso cref="Clear"/>
413 /// <seealso cref="PurgeExpired"/> 413 /// <seealso cref="PurgeExpired"/>
414 bool Set( TKey key, TValue value, long size ); 414 bool Set( TKey key, TValue value, long size );
415 415
416 /// <summary> 416 /// <summary>
417 /// Gets the <paramref name="value"/> associated with the specified <paramref name="key"/>. 417 /// Gets the <paramref name="value"/> associated with the specified <paramref name="key"/>.
418 /// </summary> 418 /// </summary>
419 /// <returns> 419 /// <returns>
420 /// <see langword="true"/>if the <see cref="ICnmCache{TKey,TValue}"/> contains an element with 420 /// <see langword="true"/>if the <see cref="ICnmCache{TKey,TValue}"/> contains an element with
421 /// the specified key; otherwise, <see langword="false"/>. 421 /// the specified key; otherwise, <see langword="false"/>.
422 /// </returns> 422 /// </returns>
423 /// <param name="key"> 423 /// <param name="key">
424 /// The key whose <paramref name="value"/> to get. 424 /// The key whose <paramref name="value"/> to get.
425 /// </param> 425 /// </param>
426 /// <param name="value"> 426 /// <param name="value">
427 /// When this method returns, the value associated with the specified <paramref name="key"/>, 427 /// When this method returns, the value associated with the specified <paramref name="key"/>,
428 /// if the <paramref name="key"/> is found; otherwise, the 428 /// if the <paramref name="key"/> is found; otherwise, the
429 /// default value for the type of the <paramref name="value"/> parameter. This parameter is passed uninitialized. 429 /// default value for the type of the <paramref name="value"/> parameter. This parameter is passed uninitialized.
430 /// </param> 430 /// </param>
431 /// <exception cref="ArgumentNullException"> 431 /// <exception cref="ArgumentNullException">
432 /// <paramref name="key"/>is <see langword="null"/>. 432 /// <paramref name="key"/>is <see langword="null"/>.
433 /// </exception> 433 /// </exception>
434 /// <seealso cref="Set"/> 434 /// <seealso cref="Set"/>
435 /// <seealso cref="Remove"/> 435 /// <seealso cref="Remove"/>
436 /// <seealso cref="RemoveRange"/> 436 /// <seealso cref="RemoveRange"/>
437 /// <seealso cref="Clear"/> 437 /// <seealso cref="Clear"/>
438 /// <seealso cref="PurgeExpired"/> 438 /// <seealso cref="PurgeExpired"/>
439 bool TryGetValue( TKey key, out TValue value ); 439 bool TryGetValue( TKey key, out TValue value );
440 } 440 }
441} 441}
generated by cgit v1.1 at 2024-11-05 17:20:56 +0000