1
0

CnmSynchronizedCache.cs 30 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747
  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. using System;
  28. using System.Collections;
  29. using System.Collections.Generic;
  30. using System.Threading;
  31. namespace OpenSim.Framework
  32. {
  33. /// <summary>
  34. /// Synchronized Cenome cache wrapper.
  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. /// Enumerator will block other threads, until enumerator's <see cref="IDisposable.Dispose"/> method is called.
  45. /// "foreach" statement is automatically calling it.
  46. /// </para>
  47. /// </remarks>
  48. public class CnmSynchronizedCache<TKey, TValue> : ICnmCache<TKey, TValue>
  49. {
  50. /// <summary>
  51. /// The cache object.
  52. /// </summary>
  53. private readonly ICnmCache<TKey, TValue> m_cache;
  54. /// <summary>
  55. /// Synchronization root.
  56. /// </summary>
  57. private readonly object m_syncRoot;
  58. /// <summary>
  59. /// Initializes a new instance of the <see cref="CnmSynchronizedCache{TKey,TValue}"/> class.
  60. /// Initializes a new instance of the <see cref="CnmSynchronizedCache{TKey,TValue}"/> class.
  61. /// </summary>
  62. /// <param name="cache">
  63. /// The cache.
  64. /// </param>
  65. private CnmSynchronizedCache(ICnmCache<TKey, TValue> cache)
  66. {
  67. m_cache = cache;
  68. m_syncRoot = m_cache.SyncRoot;
  69. }
  70. /// <summary>
  71. /// Returns a <see cref="ICnmCache{TKey,TValue}"/> wrapper that is synchronized (thread safe).
  72. /// </summary>
  73. /// <param name="cache">
  74. /// The <see cref="ICnmCache{TKey,TValue}"/> to synchronize.
  75. /// </param>
  76. /// <returns>
  77. /// A <see cref="ICnmCache{TKey,TValue}"/> wrapper that is synchronized (thread safe).
  78. /// </returns>
  79. /// <exception cref="ArgumentNullException">
  80. /// <paramref name="cache"/>is null.
  81. /// </exception>
  82. public static ICnmCache<TKey, TValue> Synchronized(ICnmCache<TKey, TValue> cache)
  83. {
  84. if (cache == null)
  85. throw new ArgumentNullException("cache");
  86. return cache.IsSynchronized ? cache : new CnmSynchronizedCache<TKey, TValue>(cache);
  87. }
  88. #region Nested type: SynchronizedEnumerator
  89. /// <summary>
  90. /// Synchronized enumerator.
  91. /// </summary>
  92. private class SynchronizedEnumerator : IEnumerator<KeyValuePair<TKey, TValue>>
  93. {
  94. /// <summary>
  95. /// Enumerator that is being synchronized.
  96. /// </summary>
  97. private readonly IEnumerator<KeyValuePair<TKey, TValue>> m_enumerator;
  98. /// <summary>
  99. /// Synchronization root.
  100. /// </summary>
  101. private object m_syncRoot;
  102. /// <summary>
  103. /// Initializes a new instance of the <see cref="SynchronizedEnumerator"/> class.
  104. /// </summary>
  105. /// <param name="enumerator">
  106. /// The enumerator that is being synchronized.
  107. /// </param>
  108. /// <param name="syncRoot">
  109. /// The sync root.
  110. /// </param>
  111. public SynchronizedEnumerator(IEnumerator<KeyValuePair<TKey, TValue>> enumerator, object syncRoot)
  112. {
  113. m_syncRoot = syncRoot;
  114. m_enumerator = enumerator;
  115. Monitor.Enter(m_syncRoot);
  116. }
  117. /// <summary>
  118. /// Finalizes an instance of the <see cref="SynchronizedEnumerator"/> class.
  119. /// </summary>
  120. ~SynchronizedEnumerator()
  121. {
  122. Dispose();
  123. }
  124. #region IEnumerator<KeyValuePair<TKey,TValue>> Members
  125. /// <summary>
  126. /// Gets the element in the collection at the current position of the enumerator.
  127. /// </summary>
  128. /// <returns>
  129. /// The element in the collection at the current position of the enumerator.
  130. /// </returns>
  131. /// <exception cref="InvalidOperationException">
  132. /// The enumerator has reach end of collection or <see cref="MoveNext"/> is not called.
  133. /// </exception>
  134. public KeyValuePair<TKey, TValue> Current
  135. {
  136. get { return m_enumerator.Current; }
  137. }
  138. /// <summary>
  139. /// Gets the current element in the collection.
  140. /// </summary>
  141. /// <returns>
  142. /// The current element in the collection.
  143. /// </returns>
  144. /// <exception cref="InvalidOperationException">
  145. /// The enumerator is positioned before the first element of the collection or after the last element.
  146. /// </exception><filterpriority>2</filterpriority>
  147. object IEnumerator.Current
  148. {
  149. get { return Current; }
  150. }
  151. /// <summary>
  152. /// Releases synchronization lock.
  153. /// </summary>
  154. public void Dispose()
  155. {
  156. if (m_syncRoot != null)
  157. {
  158. Monitor.Exit(m_syncRoot);
  159. m_syncRoot = null;
  160. }
  161. m_enumerator.Dispose();
  162. GC.SuppressFinalize(this);
  163. }
  164. /// <summary>
  165. /// Advances the enumerator to the next element of the collection.
  166. /// </summary>
  167. /// <returns>
  168. /// true if the enumerator was successfully advanced to the next element; false if the enumerator has passed the end of the collection.
  169. /// </returns>
  170. /// <exception cref="InvalidOperationException">
  171. /// The collection was modified after the enumerator was created.
  172. /// </exception>
  173. public bool MoveNext()
  174. {
  175. return m_enumerator.MoveNext();
  176. }
  177. /// <summary>
  178. /// Sets the enumerator to its initial position, which is before the first element in the collection.
  179. /// </summary>
  180. /// <exception cref="InvalidOperationException">
  181. /// The collection was modified after the enumerator was created.
  182. /// </exception>
  183. public void Reset()
  184. {
  185. m_enumerator.Reset();
  186. }
  187. #endregion
  188. }
  189. #endregion
  190. #region ICnmCache<TKey,TValue> Members
  191. /// <summary>
  192. /// Gets current count of elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
  193. /// </summary>
  194. /// <remarks>
  195. /// <para>
  196. /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count,
  197. /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element.
  198. /// </para>
  199. /// </remarks>
  200. /// <seealso cref="ICnmCache{TKey,TValue}.MaxCount"/>
  201. /// <seealso cref="ICnmCache{TKey,TValue}.IsCountLimited"/>
  202. /// <seealso cref="ICnmCache{TKey,TValue}.IsSizeLimited"/>
  203. /// <seealso cref="ICnmCache{TKey,TValue}.IsTimeLimited"/>
  204. public int Count
  205. {
  206. get
  207. {
  208. lock (m_syncRoot)
  209. {
  210. return m_cache.Count;
  211. }
  212. }
  213. }
  214. /// <summary>
  215. /// Gets or sets elements expiration time.
  216. /// </summary>
  217. /// <value>
  218. /// Elements expiration time.
  219. /// </value>
  220. /// <remarks>
  221. /// <para>
  222. /// When element has been stored in <see cref="ICnmCache{TKey,TValue}"/> longer than <see cref="ICnmCache{TKey,TValue}.ExpirationTime"/>
  223. /// and it is not accessed through <see cref="ICnmCache{TKey,TValue}.TryGetValue"/> method or element's value is
  224. /// not replaced by <see cref="ICnmCache{TKey,TValue}.Set"/> method, then it is automatically removed from the
  225. /// <see cref="ICnmCache{TKey,TValue}"/>.
  226. /// </para>
  227. /// <para>
  228. /// It is possible that <see cref="ICnmCache{TKey,TValue}"/> implementation removes element before it's expiration time,
  229. /// because total size or count of elements stored to cache is larger than <see cref="ICnmCache{TKey,TValue}.MaxSize"/> or <see cref="ICnmCache{TKey,TValue}.MaxCount"/>.
  230. /// </para>
  231. /// <para>
  232. /// It is also possible that element stays in cache longer than <see cref="ICnmCache{TKey,TValue}.ExpirationTime"/>.
  233. /// </para>
  234. /// <para>
  235. /// Calling <see cref="ICnmCache{TKey,TValue}.PurgeExpired"/> try to remove all elements that are expired.
  236. /// </para>
  237. /// <para>
  238. /// To disable time limit in cache, set <see cref="ICnmCache{TKey,TValue}.ExpirationTime"/> to <see cref="DateTime.MaxValue"/>.
  239. /// </para>
  240. /// </remarks>
  241. /// <seealso cref="ICnmCache{TKey,TValue}.IsTimeLimited"/>
  242. /// <seealso cref="ICnmCache{TKey,TValue}.IsCountLimited"/>
  243. /// <seealso cref="ICnmCache{TKey,TValue}.IsSizeLimited"/>
  244. /// <seealso cref="ICnmCache{TKey,TValue}.PurgeExpired"/>
  245. /// <seealso cref="ICnmCache{TKey,TValue}.Count"/>
  246. /// <seealso cref="ICnmCache{TKey,TValue}.MaxCount"/>
  247. /// <seealso cref="ICnmCache{TKey,TValue}.MaxSize"/>
  248. /// <seealso cref="ICnmCache{TKey,TValue}.Size"/>
  249. public TimeSpan ExpirationTime
  250. {
  251. get
  252. {
  253. lock (m_syncRoot)
  254. {
  255. return m_cache.ExpirationTime;
  256. }
  257. }
  258. set
  259. {
  260. lock (m_syncRoot)
  261. {
  262. m_cache.ExpirationTime = value;
  263. }
  264. }
  265. }
  266. /// <summary>
  267. /// Gets a value indicating whether <see cref="ICnmCache{TKey,TValue}"/> is limiting count of elements.
  268. /// </summary>
  269. /// <value>
  270. /// <see langword="true"/> if the <see cref="ICnmCache{TKey,TValue}"/> count of elements is limited;
  271. /// otherwise, <see langword="false"/>.
  272. /// </value>
  273. /// <remarks>
  274. /// <para>
  275. /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count,
  276. /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element.
  277. /// </para>
  278. /// </remarks>
  279. /// <seealso cref="ICnmCache{TKey,TValue}.Count"/>
  280. /// <seealso cref="ICnmCache{TKey,TValue}.MaxCount"/>
  281. /// <seealso cref="ICnmCache{TKey,TValue}.IsSizeLimited"/>
  282. /// <seealso cref="ICnmCache{TKey,TValue}.IsTimeLimited"/>
  283. public bool IsCountLimited
  284. {
  285. get
  286. {
  287. lock (m_syncRoot)
  288. {
  289. return m_cache.IsCountLimited;
  290. }
  291. }
  292. }
  293. /// <summary>
  294. /// Gets a value indicating whether <see cref="ICnmCache{TKey,TValue}"/> is limiting size of elements.
  295. /// </summary>
  296. /// <value>
  297. /// <see langword="true"/> if the <see cref="ICnmCache{TKey,TValue}"/> total size of elements is limited;
  298. /// otherwise, <see langword="false"/>.
  299. /// </value>
  300. /// <remarks>
  301. /// <para>
  302. /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements,
  303. /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element.
  304. /// </para>
  305. /// </remarks>
  306. /// <seealso cref="ICnmCache{TKey,TValue}.MaxElementSize"/>
  307. /// <seealso cref="ICnmCache{TKey,TValue}.Size"/>
  308. /// <seealso cref="ICnmCache{TKey,TValue}.MaxSize"/>
  309. /// <seealso cref="ICnmCache{TKey,TValue}.IsCountLimited"/>
  310. /// <seealso cref="ICnmCache{TKey,TValue}.IsTimeLimited"/>
  311. public bool IsSizeLimited
  312. {
  313. get
  314. {
  315. lock (m_syncRoot)
  316. {
  317. return m_cache.IsSizeLimited;
  318. }
  319. }
  320. }
  321. /// <summary>
  322. /// Gets a value indicating whether or not access to the <see cref="ICnmCache{TKey,TValue}"/> is synchronized (thread safe).
  323. /// </summary>
  324. /// <value>
  325. /// <see langword="true"/> if access to the <see cref="ICnmCache{TKey,TValue}"/> is synchronized (thread safe);
  326. /// otherwise, <see langword="false"/>.
  327. /// </value>
  328. /// <remarks>
  329. /// <para>
  330. /// To get synchronized (thread safe) access to <see cref="ICnmCache{TKey,TValue}"/> object, use
  331. /// <see cref="CnmSynchronizedCache{TKey,TValue}.Synchronized"/> in <see cref="CnmSynchronizedCache{TKey,TValue}"/> class
  332. /// to retrieve synchronized wrapper for <see cref="ICnmCache{TKey,TValue}"/> object.
  333. /// </para>
  334. /// </remarks>
  335. /// <seealso cref="ICnmCache{TKey,TValue}.SyncRoot"/>
  336. /// <seealso cref="CnmSynchronizedCache{TKey,TValue}"/>
  337. public bool IsSynchronized
  338. {
  339. get { return true; }
  340. }
  341. /// <summary>
  342. /// Gets a value indicating whether elements stored to <see cref="ICnmCache{TKey,TValue}"/> have limited inactivity time.
  343. /// </summary>
  344. /// <value>
  345. /// <see langword="true"/> if the <see cref="ICnmCache{TKey,TValue}"/> has a fixed total size of elements;
  346. /// otherwise, <see langword="false"/>.
  347. /// </value>
  348. /// <remarks>
  349. /// If <see cref="ICnmCache{TKey,TValue}"/> have limited inactivity time and element is not accessed through <see cref="ICnmCache{TKey,TValue}.Set"/>
  350. /// or <see cref="ICnmCache{TKey,TValue}.TryGetValue"/> methods in <see cref="ICnmCache{TKey,TValue}.ExpirationTime"/> , then element is automatically removed from
  351. /// the cache. Depending on implementation of the <see cref="ICnmCache{TKey,TValue}"/>, some of the elements may
  352. /// stay longer in cache.
  353. /// </remarks>
  354. /// <seealso cref="ICnmCache{TKey,TValue}.ExpirationTime"/>
  355. /// <seealso cref="ICnmCache{TKey,TValue}.PurgeExpired"/>
  356. /// <seealso cref="ICnmCache{TKey,TValue}.IsCountLimited"/>
  357. /// <seealso cref="ICnmCache{TKey,TValue}.IsSizeLimited"/>
  358. public bool IsTimeLimited
  359. {
  360. get
  361. {
  362. lock (m_syncRoot)
  363. {
  364. return m_cache.IsTimeLimited;
  365. }
  366. }
  367. }
  368. /// <summary>
  369. /// Gets or sets maximal allowed count of elements that can be stored to <see cref="ICnmCache{TKey,TValue}"/>.
  370. /// </summary>
  371. /// <value>
  372. /// <see cref="int.MaxValue"/>, if <see cref="ICnmCache{TKey,TValue}"/> is not limited by count of elements;
  373. /// otherwise maximal allowed count of elements.
  374. /// </value>
  375. /// <remarks>
  376. /// <para>
  377. /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count,
  378. /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element.
  379. /// </para>
  380. /// </remarks>
  381. public int MaxCount
  382. {
  383. get
  384. {
  385. lock (m_syncRoot)
  386. {
  387. return m_cache.MaxCount;
  388. }
  389. }
  390. set
  391. {
  392. lock (m_syncRoot)
  393. {
  394. m_cache.MaxCount = value;
  395. }
  396. }
  397. }
  398. /// <summary>
  399. /// <para>Gets maximal allowed element size.</para>
  400. /// </summary>
  401. /// <value>
  402. /// Maximal allowed element size.
  403. /// </value>
  404. /// <remarks>
  405. /// <para>
  406. /// If element's size is larger than <see cref="ICnmCache{TKey,TValue}.MaxElementSize"/>, then element is
  407. /// not added to the <see cref="ICnmCache{TKey,TValue}"/>.
  408. /// </para>
  409. /// </remarks>
  410. /// <seealso cref="ICnmCache{TKey,TValue}.Set"/>
  411. /// <seealso cref="ICnmCache{TKey,TValue}.IsSizeLimited"/>
  412. /// <seealso cref="ICnmCache{TKey,TValue}.Size"/>
  413. /// <seealso cref="ICnmCache{TKey,TValue}.MaxSize"/>
  414. public long MaxElementSize
  415. {
  416. get
  417. {
  418. lock (m_syncRoot)
  419. {
  420. return m_cache.MaxElementSize;
  421. }
  422. }
  423. }
  424. /// <summary>
  425. /// Gets or sets maximal allowed total size for elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
  426. /// </summary>
  427. /// <value>
  428. /// Maximal allowed total size for elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
  429. /// </value>
  430. /// <remarks>
  431. /// <para>
  432. /// Normally size is total bytes used by elements in the cache. But it can be any other suitable unit of measure.
  433. /// </para>
  434. /// <para>
  435. /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements,
  436. /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element.
  437. /// </para>
  438. /// </remarks>
  439. /// <exception cref="ArgumentOutOfRangeException">value is less than 0.</exception>
  440. /// <seealso cref="ICnmCache{TKey,TValue}.MaxElementSize"/>
  441. /// <seealso cref="ICnmCache{TKey,TValue}.IsSizeLimited"/>
  442. /// <seealso cref="ICnmCache{TKey,TValue}.Size"/>
  443. public long MaxSize
  444. {
  445. get
  446. {
  447. lock (m_syncRoot)
  448. {
  449. return m_cache.MaxSize;
  450. }
  451. }
  452. set
  453. {
  454. lock (m_syncRoot)
  455. {
  456. m_cache.MaxSize = value;
  457. }
  458. }
  459. }
  460. /// <summary>
  461. /// Gets total size of elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
  462. /// </summary>
  463. /// <value>
  464. /// Total size of elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
  465. /// </value>
  466. /// <remarks>
  467. /// <para>
  468. /// Normally bytes, but can be any suitable unit of measure.
  469. /// </para>
  470. /// <para>
  471. /// Element's size is given when element is added or replaced by <see cref="ICnmCache{TKey,TValue}.Set"/> method.
  472. /// </para>
  473. /// <para>
  474. /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements,
  475. /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element.
  476. /// </para>
  477. /// </remarks>
  478. /// <seealso cref="ICnmCache{TKey,TValue}.MaxElementSize"/>
  479. /// <seealso cref="ICnmCache{TKey,TValue}.IsSizeLimited"/>
  480. /// <seealso cref="ICnmCache{TKey,TValue}.MaxSize"/>
  481. /// <seealso cref="ICnmCache{TKey,TValue}.IsCountLimited"/>
  482. /// <seealso cref="ICnmCache{TKey,TValue}.ExpirationTime"/>
  483. public long Size
  484. {
  485. get
  486. {
  487. lock (m_syncRoot)
  488. {
  489. return m_cache.Size;
  490. }
  491. }
  492. }
  493. /// <summary>
  494. /// Gets an object that can be used to synchronize access to the <see cref="ICnmCache{TKey,TValue}"/>.
  495. /// </summary>
  496. /// <value>
  497. /// An object that can be used to synchronize access to the <see cref="ICnmCache{TKey,TValue}"/>.
  498. /// </value>
  499. /// <remarks>
  500. /// <para>
  501. /// To get synchronized (thread safe) access to <see cref="ICnmCache{TKey,TValue}"/>, use <see cref="CnmSynchronizedCache{TKey,TValue}"/>
  502. /// method <see cref="CnmSynchronizedCache{TKey,TValue}.Synchronized"/> to retrieve synchronized wrapper interface to
  503. /// <see cref="ICnmCache{TKey,TValue}"/>.
  504. /// </para>
  505. /// </remarks>
  506. /// <seealso cref="ICnmCache{TKey,TValue}.IsSynchronized"/>
  507. /// <seealso cref="CnmSynchronizedCache{TKey,TValue}"/>
  508. public object SyncRoot
  509. {
  510. get { return m_syncRoot; }
  511. }
  512. /// <summary>
  513. /// Removes all elements from the <see cref="ICnmCache{TKey,TValue}"/>.
  514. /// </summary>
  515. /// <seealso cref="ICnmCache{TKey,TValue}.Set"/>
  516. /// <seealso cref="ICnmCache{TKey,TValue}.Remove"/>
  517. /// <seealso cref="ICnmCache{TKey,TValue}.RemoveRange"/>
  518. /// <seealso cref="ICnmCache{TKey,TValue}.TryGetValue"/>
  519. /// <seealso cref="ICnmCache{TKey,TValue}.PurgeExpired"/>
  520. public void Clear()
  521. {
  522. lock (m_syncRoot)
  523. {
  524. m_cache.Clear();
  525. }
  526. }
  527. /// <summary>
  528. /// Returns an enumerator that iterates through the elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
  529. /// </summary>
  530. /// <returns>
  531. /// A <see cref="IEnumerator{T}"/> that can be used to iterate through the collection.
  532. /// </returns>
  533. /// <filterpriority>1</filterpriority>
  534. public IEnumerator<KeyValuePair<TKey, TValue>> GetEnumerator()
  535. {
  536. lock (m_syncRoot)
  537. {
  538. return new SynchronizedEnumerator(m_cache.GetEnumerator(), m_syncRoot);
  539. }
  540. }
  541. /// <summary>
  542. /// Purge expired elements from the <see cref="ICnmCache{TKey,TValue}"/>.
  543. /// </summary>
  544. /// <remarks>
  545. /// <para>
  546. /// Element becomes expired when last access time to it has been longer time than <see cref="ICnmCache{TKey,TValue}.ExpirationTime"/>.
  547. /// </para>
  548. /// <para>
  549. /// Depending on <see cref="ICnmCache{TKey,TValue}"/> implementation, some of expired elements
  550. /// may stay longer than <see cref="ICnmCache{TKey,TValue}.ExpirationTime"/> in the cache.
  551. /// </para>
  552. /// </remarks>
  553. /// <seealso cref="ICnmCache{TKey,TValue}.IsTimeLimited"/>
  554. /// <seealso cref="ICnmCache{TKey,TValue}.ExpirationTime"/>
  555. /// <seealso cref="ICnmCache{TKey,TValue}.Set"/>
  556. /// <seealso cref="ICnmCache{TKey,TValue}.Remove"/>
  557. /// <seealso cref="ICnmCache{TKey,TValue}.RemoveRange"/>
  558. /// <seealso cref="ICnmCache{TKey,TValue}.TryGetValue"/>
  559. /// <seealso cref="ICnmCache{TKey,TValue}.Clear"/>
  560. public void PurgeExpired()
  561. {
  562. lock (m_syncRoot)
  563. {
  564. m_cache.PurgeExpired();
  565. }
  566. }
  567. /// <summary>
  568. /// Removes element associated with <paramref name="key"/> from the <see cref="ICnmCache{TKey,TValue}"/>.
  569. /// </summary>
  570. /// <param name="key">
  571. /// The key that is associated with element to remove from the <see cref="ICnmCache{TKey,TValue}"/>.
  572. /// </param>
  573. /// <exception cref="ArgumentNullException">
  574. /// <paramref name="key"/>is <see langword="null"/>.
  575. /// </exception>
  576. /// <seealso cref="ICnmCache{TKey,TValue}.Set"/>
  577. /// <seealso cref="ICnmCache{TKey,TValue}.RemoveRange"/>
  578. /// <seealso cref="ICnmCache{TKey,TValue}.TryGetValue"/>
  579. /// <seealso cref="ICnmCache{TKey,TValue}.Clear"/>
  580. /// <seealso cref="ICnmCache{TKey,TValue}.PurgeExpired"/>
  581. public void Remove(TKey key)
  582. {
  583. lock (m_syncRoot)
  584. {
  585. m_cache.Remove(key);
  586. }
  587. }
  588. /// <summary>
  589. /// Removes elements that are associated with one of <paramref name="keys"/> from the <see cref="ICnmCache{TKey,TValue}"/>.
  590. /// </summary>
  591. /// <param name="keys">
  592. /// The keys that are associated with elements to remove from the <see cref="ICnmCache{TKey,TValue}"/>.
  593. /// </param>
  594. /// <exception cref="ArgumentNullException">
  595. /// <paramref name="keys"/>is <see langword="null"/>.
  596. /// </exception>
  597. /// <seealso cref="ICnmCache{TKey,TValue}.Set"/>
  598. /// <seealso cref="ICnmCache{TKey,TValue}.Remove"/>
  599. /// <seealso cref="ICnmCache{TKey,TValue}.TryGetValue"/>
  600. /// <seealso cref="ICnmCache{TKey,TValue}.Clear"/>
  601. /// <seealso cref="ICnmCache{TKey,TValue}.PurgeExpired"/>
  602. public void RemoveRange(IEnumerable<TKey> keys)
  603. {
  604. lock (m_syncRoot)
  605. {
  606. m_cache.RemoveRange(keys);
  607. }
  608. }
  609. /// <summary>
  610. /// Add or replace an element with the provided <paramref name="key"/>, <paramref name="value"/> and <paramref name="size"/> to
  611. /// <see cref="ICnmCache{TKey,TValue}"/>.
  612. /// </summary>
  613. /// <param name="key">
  614. /// The object used as the key of the element. Can't be <see langword="null"/> reference.
  615. /// </param>
  616. /// <param name="value">
  617. /// The object used as the value of the element to add or replace. <see langword="null"/> is allowed.
  618. /// </param>
  619. /// <param name="size">
  620. /// The element's size. Normally bytes, but can be any suitable unit of measure.
  621. /// </param>
  622. /// <returns>
  623. /// <see langword="true"/>if element has been added successfully to the <see cref="ICnmCache{TKey,TValue}"/>;
  624. /// otherwise <see langword="false"/>.
  625. /// </returns>
  626. /// <exception cref="ArgumentNullException">
  627. /// <paramref name="key"/>is <see langword="null"/>.
  628. /// </exception>
  629. /// <exception cref="ArgumentOutOfRangeException">
  630. /// The element's <paramref name="size"/> is less than 0.
  631. /// </exception>
  632. /// <remarks>
  633. /// <para>
  634. /// If element's <paramref name="size"/> is larger than <see cref="ICnmCache{TKey,TValue}.MaxElementSize"/>, then element is
  635. /// not added to the <see cref="ICnmCache{TKey,TValue}"/>, however - possible older element is
  636. /// removed from the <see cref="ICnmCache{TKey,TValue}"/>.
  637. /// </para>
  638. /// <para>
  639. /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements,
  640. /// <see cref="ICnmCache{TKey,TValue}"/>will remove less recently used elements until it can fit an new element.
  641. /// </para>
  642. /// <para>
  643. /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count,
  644. /// <see cref="ICnmCache{TKey,TValue}"/>will remove less recently used elements until it can fit an new element.
  645. /// </para>
  646. /// </remarks>
  647. /// <seealso cref="ICnmCache{TKey,TValue}.IsSizeLimited"/>
  648. /// <seealso cref="ICnmCache{TKey,TValue}.IsCountLimited"/>
  649. /// <seealso cref="ICnmCache{TKey,TValue}.Remove"/>
  650. /// <seealso cref="ICnmCache{TKey,TValue}.RemoveRange"/>
  651. /// <seealso cref="ICnmCache{TKey,TValue}.TryGetValue"/>
  652. /// <seealso cref="ICnmCache{TKey,TValue}.Clear"/>
  653. /// <seealso cref="ICnmCache{TKey,TValue}.PurgeExpired"/>
  654. public bool Set(TKey key, TValue value, long size)
  655. {
  656. lock (m_syncRoot)
  657. {
  658. return m_cache.Set(key, value, size);
  659. }
  660. }
  661. /// <summary>
  662. /// Gets the <paramref name="value"/> associated with the specified <paramref name="key"/>.
  663. /// </summary>
  664. /// <returns>
  665. /// <see langword="true"/>if the <see cref="ICnmCache{TKey,TValue}"/> contains an element with
  666. /// the specified key; otherwise, <see langword="false"/>.
  667. /// </returns>
  668. /// <param name="key">
  669. /// The key whose <paramref name="value"/> to get.
  670. /// </param>
  671. /// <param name="value">
  672. /// When this method returns, the value associated with the specified <paramref name="key"/>,
  673. /// if the <paramref name="key"/> is found; otherwise, the
  674. /// default value for the type of the <paramref name="value"/> parameter. This parameter is passed uninitialized.
  675. /// </param>
  676. /// <exception cref="ArgumentNullException">
  677. /// <paramref name="key"/>is <see langword="null"/>.
  678. /// </exception>
  679. /// <seealso cref="ICnmCache{TKey,TValue}.Set"/>
  680. /// <seealso cref="ICnmCache{TKey,TValue}.Remove"/>
  681. /// <seealso cref="ICnmCache{TKey,TValue}.RemoveRange"/>
  682. /// <seealso cref="ICnmCache{TKey,TValue}.Clear"/>
  683. /// <seealso cref="ICnmCache{TKey,TValue}.PurgeExpired"/>
  684. public bool TryGetValue(TKey key, out TValue value)
  685. {
  686. lock (m_syncRoot)
  687. {
  688. return m_cache.TryGetValue(key, out value);
  689. }
  690. }
  691. /// <summary>
  692. /// Returns an enumerator that iterates through the elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
  693. /// </summary>
  694. /// <returns>
  695. /// A <see cref="IEnumerator"/> that can be used to iterate through the collection.
  696. /// </returns>
  697. /// <filterpriority>1</filterpriority>
  698. IEnumerator IEnumerable.GetEnumerator()
  699. {
  700. return GetEnumerator();
  701. }
  702. #endregion
  703. }
  704. }