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