Thank you Imaze Rhiano for a patch that implements Cenome Memory Asset Cache (Mantis #3759)

See the files: bin/config-include/GridCommon.ini.example and bin/config-include/StandaloneCommon.ini.example to configure and enable this caching method.
author: Dahlia Trimble 2009-06-02 22:42:47 +0000
committer: Dahlia Trimble 2009-06-02 22:42:47 +0000
commit: b38be1a7fdf71a7d3c6d6f761590827b1f45483c (patch)
tree: 2be409eb714dfd93d78e50d8b0def07b8e9758e1 /OpenSim/Framework/ICnmCache.cs
parent: Thank you kindly, MattSetzer, for a patch that solves a Mantis: (diff)
download: opensim-SC_OLD-b38be1a7fdf71a7d3c6d6f761590827b1f45483c.zip
opensim-SC_OLD-b38be1a7fdf71a7d3c6d6f761590827b1f45483c.tar.gz
opensim-SC_OLD-b38be1a7fdf71a7d3c6d6f761590827b1f45483c.tar.bz2
opensim-SC_OLD-b38be1a7fdf71a7d3c6d6f761590827b1f45483c.tar.xz
1 files changed, 441 insertions, 0 deletions
diff --git a/OpenSim/Framework/ICnmCache.cs b/OpenSim/Framework/ICnmCache.cs
new file mode 100644
index 0000000..cba8a7f
--- /dev/null
+++ b/OpenSim/Framework/ICnmCache.cs
@@ -0,0 +1,441 @@
+/*
+ * Copyright (c) Contributors, http://opensimulator.org/
+ * See CONTRIBUTORS.TXT for a full list of copyright holders.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *     * Redistributions of source code must retain the above copyright
+ *       notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above copyright
+ *       notice, this list of conditions and the following disclaimer in the
+ *       documentation and/or other materials provided with the distribution.
+ *     * Neither the name of the OpenSimulator Project nor the
+ *       names of its contributors may be used to endorse or promote products
+ *       derived from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY
+ * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+using System;
+using System.Collections.Generic;
+namespace OpenSim.Framework
+{
+    /// <summary>
+    /// Represent generic cache to store key/value pairs (elements) limited by time, size and count of elements.
+    /// </summary>
+    /// <typeparam name="TKey">
+    /// The type of keys in the cache. 
+    /// </typeparam>
+    /// <typeparam name="TValue">
+    /// The type of values in the cache. 
+    /// </typeparam>
+    /// <remarks>
+    /// <para>
+    /// Cache store limitations:
+    /// </para>
+    /// <list type="table">
+    /// <listheader>
+    /// <term>Limitation</term>
+    /// <description>Description</description>
+    /// </listheader>
+    /// <item>
+    /// <term>Time</term>
+    /// <description>
+    /// Element that is not accessed through <see cref="TryGetValue"/> or <see cref="Set"/> in last <see cref="ExpirationTime"/> are 
+    /// removed from the cache automatically. Depending on implementation of the cache some of elements may stay longer in cache. 
+    /// <see cref="IsTimeLimited"/> returns <see langword="true"/>, if cache is limited by time.
+    /// </description>
+    /// </item>
+    /// <item>
+    /// <term>Count</term>
+    /// <description>
+    /// When adding an new element to cache that already have <see cref="MaxCount"/> of elements, cache will remove less recently
+    /// used element(s) from the cache, until element fits to cache. 
+    /// <see cref="IsCountLimited"/> returns <see langword="true"/>, if cache is limiting element count.
+    /// </description>
+    /// </item>
+    /// <item>
+    /// <term>Size</term>
+    /// <description>
+    /// <description>
+    /// When adding an new element to cache that already have <see cref="MaxSize"/> of elements, cache will remove less recently
+    /// used element(s) from the cache, until element fits to cache. 
+    /// <see cref="IsSizeLimited"/> returns <see langword="true"/>, if cache is limiting total size of elements. 
+    /// Normally size is bytes used by element in the cache. But it can be any other suitable unit of measure.
+    /// </description>
+    /// </description>
+    /// </item>
+    /// </list>
+    /// </remarks>
+    public interface ICnmCache<TKey, TValue> : IEnumerable<KeyValuePair<TKey, TValue>>
+    {
+        /// <summary>
+        /// Gets current count of elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count, 
+        /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element. 
+        /// </para>
+        /// </remarks>
+        /// <seealso cref="MaxCount"/>
+        /// <seealso cref="IsCountLimited"/>
+        /// <seealso cref="IsSizeLimited"/>
+        /// <seealso cref="IsTimeLimited"/>
+        int Count { get; }
+        /// <summary>
+        /// Gets or sets elements expiration time.
+        /// </summary>
+        /// <value>
+        /// Elements expiration time.
+        /// </value>
+        /// <remarks>
+        /// <para>
+        /// When element has been stored in <see cref="ICnmCache{TKey,TValue}"/> longer than <see cref="ExpirationTime"/> 
+        /// and it is not accessed through <see cref="TryGetValue"/> method or element's value is 
+        /// not replaced by <see cref="Set"/> method, then it is automatically removed from the 
+        /// <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </para>
+        /// <para>
+        /// It is possible that <see cref="ICnmCache{TKey,TValue}"/> implementation removes element before it's expiration time, 
+        /// because total size or count of elements stored to cache is larger than <see cref="MaxSize"/> or <see cref="MaxCount"/>.
+        /// </para>
+        /// <para>
+        /// It is also possible that element stays in cache longer than <see cref="ExpirationTime"/>.
+        /// </para>
+        /// <para>
+        /// Calling <see cref="PurgeExpired"/> try to remove all elements that are expired.
+        /// </para>
+        /// <para>
+        /// To disable time limit in cache, set <see cref="ExpirationTime"/> to <see cref="DateTime.MaxValue"/>.
+        /// </para>
+        /// </remarks>
+        /// <seealso cref="IsTimeLimited"/>
+        /// <seealso cref="IsCountLimited"/>
+        /// <seealso cref="IsSizeLimited"/>
+        /// <seealso cref="PurgeExpired"/>
+        /// <seealso cref="Count"/>
+        /// <seealso cref="MaxCount"/>
+        /// <seealso cref="MaxSize"/>
+        /// <seealso cref="Size"/>
+        TimeSpan ExpirationTime { get; set; }
+        /// <summary>
+        /// Gets a value indicating whether or not access to the <see cref="ICnmCache{TKey,TValue}"/> is synchronized (thread safe).
+        /// </summary>
+        /// <value>
+        /// <see langword="true"/> if access to the <see cref="ICnmCache{TKey,TValue}"/> is synchronized (thread safe); 
+        /// otherwise, <see langword="false"/>. 
+        /// </value>
+        /// <remarks>
+        /// <para>
+        /// To get synchronized (thread safe) access to <see cref="ICnmCache{TKey,TValue}"/> object, use 
+        /// <see cref="CnmSynchronizedCache{TKey,TValue}.Synchronized"/> in <see cref="CnmSynchronizedCache{TKey,TValue}"/> class
+        /// to retrieve synchronized wrapper for <see cref="ICnmCache{TKey,TValue}"/> object.
+        /// </para>
+        /// </remarks>
+        /// <seealso cref="SyncRoot"/>
+        /// <seealso cref="CnmSynchronizedCache{TKey,TValue}"/>
+        bool IsSynchronized { get; }
+        /// <summary>
+        /// Gets a value indicating whether <see cref="ICnmCache{TKey,TValue}"/> is limiting count of elements.
+        /// </summary>
+        /// <value>
+        /// <see langword="true"/> if the <see cref="ICnmCache{TKey,TValue}"/> count of elements is limited; 
+        /// otherwise, <see langword="false"/>. 
+        /// </value>
+        /// <remarks>
+        /// <para>
+        /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count, 
+        /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element. 
+        /// </para>
+        /// </remarks>
+        /// <seealso cref="Count"/>
+        /// <seealso cref="MaxCount"/> 
+        /// <seealso cref="IsSizeLimited"/>
+        /// <seealso cref="IsTimeLimited"/>
+        bool IsCountLimited { get; }
+        /// <summary>
+        /// Gets a value indicating whether <see cref="ICnmCache{TKey,TValue}"/> is limiting size of elements.
+        /// </summary>
+        /// <value>
+        /// <see langword="true"/> if the <see cref="ICnmCache{TKey,TValue}"/> total size of elements is limited; 
+        /// otherwise, <see langword="false"/>. 
+        /// </value>
+        /// <remarks>
+        /// <para>
+        /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements, 
+        /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element. 
+        /// </para>
+        /// </remarks>        
+        /// <seealso cref="MaxElementSize"/>
+        /// <seealso cref="Size"/>
+        /// <seealso cref="MaxSize"/>        
+        /// <seealso cref="IsCountLimited"/>
+        /// <seealso cref="IsTimeLimited"/>
+        bool IsSizeLimited { get; }
+        /// <summary>
+        /// Gets a value indicating whether elements stored to <see cref="ICnmCache{TKey,TValue}"/> have limited inactivity time.        
+        /// </summary>
+        /// <value>
+        /// <see langword="true"/> if the <see cref="ICnmCache{TKey,TValue}"/> has a fixed total size of elements; 
+        /// otherwise, <see langword="false"/>. 
+        /// </value>
+        /// <remarks>
+        /// If <see cref="ICnmCache{TKey,TValue}"/> have limited inactivity time and element is not accessed through <see cref="Set"/>
+        /// or <see cref="TryGetValue"/> methods in <see cref="ExpirationTime"/> , then element is automatically removed from 
+        /// the cache. Depending on implementation of the <see cref="ICnmCache{TKey,TValue}"/>, some of the elements may 
+        /// stay longer in cache.
+        /// </remarks>        
+        /// <seealso cref="ExpirationTime"/>
+        /// <seealso cref="PurgeExpired"/>
+        /// <seealso cref="IsCountLimited"/>
+        /// <seealso cref="IsSizeLimited"/>
+        bool IsTimeLimited { get; }
+        
+        /// <summary>
+        /// Gets or sets maximal allowed count of elements that can be stored to <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </summary>
+        /// <value>
+        /// <see cref="int.MaxValue"/>, if <see cref="ICnmCache{TKey,TValue}"/> is not limited by count of elements; 
+        /// otherwise maximal allowed count of elements.
+        /// </value>
+        /// <remarks>
+        /// <para>
+        /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count, 
+        /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element. 
+        /// </para>
+        /// </remarks>
+        int MaxCount { get; set; }
+        /// <summary>
+        /// <para>Gets maximal allowed element size.</para>
+        /// </summary>
+        /// <value>
+        /// Maximal allowed element size.
+        /// </value>
+        /// <remarks>
+        /// <para>
+        /// If element's size is larger than <see cref="MaxElementSize"/>, then element is 
+        /// not added to the <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </para>
+        /// </remarks>
+        /// <seealso cref="Set"/>
+        /// <seealso cref="IsSizeLimited"/>
+        /// <seealso cref="Size"/>
+        /// <seealso cref="MaxSize"/>        
+        long MaxElementSize { get; }
+        /// <summary>
+        /// Gets or sets maximal allowed total size for elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </summary>
+        /// <value>
+        /// Maximal allowed total size for elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </value>
+        /// <remarks>        
+        /// <para>
+        /// Normally size is total bytes used by elements in the cache. But it can be any other suitable unit of measure.
+        /// </para>
+        /// <para>
+        /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements, 
+        /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element. 
+        /// </para>
+        /// </remarks>
+        /// <exception cref="ArgumentOutOfRangeException">value is less than 0.</exception>
+        /// <seealso cref="MaxElementSize"/>
+        /// <seealso cref="IsSizeLimited"/>
+        /// <seealso cref="Size"/>
+        long MaxSize { get; set; }
+        /// <summary>
+        /// Gets total size of elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </summary>
+        /// <value>
+        /// Total size of elements stored to <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </value>
+        /// <remarks>
+        /// <para>
+        /// Normally bytes, but can be any suitable unit of measure.
+        /// </para>
+        /// <para>
+        /// Element's size is given when element is added or replaced by <see cref="Set"/> method. 
+        /// </para>
+        /// <para>
+        /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements, 
+        /// <see cref="ICnmCache{TKey,TValue}"/> will remove less recently used elements until it can fit an new element. 
+        /// </para>
+        /// </remarks>        
+        /// <seealso cref="MaxElementSize"/>
+        /// <seealso cref="IsSizeLimited"/>
+        /// <seealso cref="MaxSize"/>        
+        /// <seealso cref="IsCountLimited"/>
+        /// <seealso cref="ExpirationTime"/>
+        long Size { get; }
+        /// <summary>
+        /// Gets an object that can be used to synchronize access to the <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </summary>
+        /// <value>        
+        /// An object that can be used to synchronize access to the <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </value>        
+        /// <remarks>
+        /// <para>
+        /// To get synchronized (thread safe) access to <see cref="ICnmCache{TKey,TValue}"/>, use <see cref="CnmSynchronizedCache{TKey,TValue}"/> 
+        /// method <see cref="CnmSynchronizedCache{TKey,TValue}.Synchronized"/> to retrieve synchronized wrapper interface to 
+        /// <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </para>
+        /// </remarks>
+        /// <seealso cref="IsSynchronized"/>
+        /// <seealso cref="CnmSynchronizedCache{TKey,TValue}"/>
+        object SyncRoot { get; }
+        /// <summary>
+        /// Removes all elements from the <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </summary>
+        /// <seealso cref="Set"/>
+        /// <seealso cref="Remove"/>
+        /// <seealso cref="RemoveRange"/>
+        /// <seealso cref="TryGetValue"/>
+        /// <seealso cref="PurgeExpired"/>
+        void Clear();
+        /// <summary>
+        /// Purge expired elements from the <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Element becomes expired when last access time to it has been longer time than <see cref="ExpirationTime"/>.
+        /// </para>
+        /// <para>
+        /// Depending on <see cref="ICnmCache{TKey,TValue}"/> implementation, some of expired elements
+        /// may stay longer than <see cref="ExpirationTime"/> in the cache.        
+        /// </para>
+        /// </remarks>
+        /// <seealso cref="IsTimeLimited"/>
+        /// <seealso cref="ExpirationTime"/>
+        /// <seealso cref="Set"/>
+        /// <seealso cref="Remove"/>
+        /// <seealso cref="RemoveRange"/>
+        /// <seealso cref="TryGetValue"/>
+        /// <seealso cref="Clear"/>
+        void PurgeExpired();
+        /// <summary>
+        /// Removes element associated with <paramref name="key"/> from the <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </summary>
+        /// <param name="key">
+        /// The key that is associated with element to remove from the <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </param>
+        /// <exception cref="ArgumentNullException">
+        /// <paramref name="key"/> is <see langword="null"/>.
+        /// </exception>
+        /// <seealso cref="Set"/>
+        /// <seealso cref="RemoveRange"/>
+        /// <seealso cref="TryGetValue"/>
+        /// <seealso cref="Clear"/>
+        /// <seealso cref="PurgeExpired"/>
+        void Remove( TKey key );
+        /// <summary>
+        /// Removes elements that are associated with one of <paramref name="keys"/> from the <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </summary>
+        /// <param name="keys">
+        /// The keys that are associated with elements to remove from the <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </param>
+        /// <exception cref="ArgumentNullException">
+        /// <paramref name="keys"/> is <see langword="null"/>.
+        /// </exception>
+        /// <seealso cref="Set"/>
+        /// <seealso cref="Remove"/>
+        /// <seealso cref="TryGetValue"/>
+        /// <seealso cref="Clear"/>
+        /// <seealso cref="PurgeExpired"/>
+        void RemoveRange( IEnumerable<TKey> keys );
+        /// <summary>
+        /// Add or replace an element with the provided <paramref name="key"/>, <paramref name="value"/> and <paramref name="size"/> to 
+        /// <see cref="ICnmCache{TKey,TValue}"/>.
+        /// </summary>
+        /// <param name="key">
+        /// The object used as the key of the element. Can't be <see langword="null"/> reference.
+        /// </param>
+        /// <param name="value">
+        /// The object used as the value of the element to add or replace. <see langword="null"/> is allowed.
+        /// </param>
+        /// <param name="size">
+        /// The element's size. Normally bytes, but can be any suitable unit of measure.
+        /// </param>
+        /// <returns>
+        /// <see langword="true"/> if element has been added successfully to the <see cref="ICnmCache{TKey,TValue}"/>; 
+        /// otherwise <see langword="false"/>.
+        /// </returns>
+        /// <exception cref="ArgumentNullException">
+        /// <paramref name="key"/>is <see langword="null"/>.
+        /// </exception>
+        /// <exception cref="ArgumentOutOfRangeException">
+        /// The element's <paramref name="size"/> is less than 0.
+        /// </exception>
+        /// <remarks>
+        /// <para>
+        /// If element's <paramref name="size"/> is larger than <see cref="MaxElementSize"/>, then element is 
+        /// not added to the <see cref="ICnmCache{TKey,TValue}"/>, however - possible older element is 
+        /// removed from the <see cref="ICnmCache{TKey,TValue}"/>. 
+        /// </para>
+        /// <para>
+        /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting total size of elements, 
+        /// <see cref="ICnmCache{TKey,TValue}"/>will remove less recently used elements until it can fit an new element. 
+        /// </para>
+        /// <para>
+        /// When adding an new element to <see cref="ICnmCache{TKey,TValue}"/> that is limiting element count, 
+        /// <see cref="ICnmCache{TKey,TValue}"/>will remove less recently used elements until it can fit an new element. 
+        /// </para>
+        /// </remarks>
+        /// <seealso cref="IsSizeLimited"/>
+        /// <seealso cref="IsCountLimited"/>
+        /// <seealso cref="Remove"/>
+        /// <seealso cref="RemoveRange"/>
+        /// <seealso cref="TryGetValue"/>
+        /// <seealso cref="Clear"/>
+        /// <seealso cref="PurgeExpired"/>
+        bool Set( TKey key, TValue value, long size );
+        /// <summary>
+        /// Gets the <paramref name="value"/> associated with the specified <paramref name="key"/>.
+        /// </summary>
+        /// <returns>
+        /// <see langword="true"/>if the <see cref="ICnmCache{TKey,TValue}"/> contains an element with 
+        /// the specified key; otherwise, <see langword="false"/>.        
+        /// </returns>
+        /// <param name="key">
+        /// The key whose <paramref name="value"/> to get.
+        /// </param>
+        /// <param name="value">
+        /// When this method returns, the value associated with the specified <paramref name="key"/>, 
+        /// if the <paramref name="key"/> is found; otherwise, the 
+        /// default value for the type of the <paramref name="value"/> parameter. This parameter is passed uninitialized.
+        /// </param>
+        /// <exception cref="ArgumentNullException">
+        /// <paramref name="key"/>is <see langword="null"/>.
+        /// </exception>
+        /// <seealso cref="Set"/>
+        /// <seealso cref="Remove"/>
+        /// <seealso cref="RemoveRange"/>
+        /// <seealso cref="Clear"/>
+        /// <seealso cref="PurgeExpired"/>
+        bool TryGetValue( TKey key, out TValue value );
+    }
+}
author	Dahlia Trimble	2009-06-02 22:42:47 +0000
committer	Dahlia Trimble	2009-06-02 22:42:47 +0000
commit	b38be1a7fdf71a7d3c6d6f761590827b1f45483c (patch)
tree	2be409eb714dfd93d78e50d8b0def07b8e9758e1 /OpenSim/Framework/ICnmCache.cs
parent	Thank you kindly, MattSetzer, for a patch that solves a Mantis: (diff)
download	opensim-SC_OLD-b38be1a7fdf71a7d3c6d6f761590827b1f45483c.zip opensim-SC_OLD-b38be1a7fdf71a7d3c6d6f761590827b1f45483c.tar.gz opensim-SC_OLD-b38be1a7fdf71a7d3c6d6f761590827b1f45483c.tar.bz2 opensim-SC_OLD-b38be1a7fdf71a7d3c6d6f761590827b1f45483c.tar.xz

diff --git a/OpenSim/Framework/ICnmCache.cs b/OpenSim/Framework/ICnmCache.cs new file mode 100644 index 0000000..cba8a7f --- /dev/null +++ b/OpenSim/Framework/ICnmCache.cs
@@ -0,0 +1,441 @@
	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
	28	using System;
	29	using System.Collections.Generic;
	30
	31	namespace 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	}