Click or drag to resize

Cache Class

ASCOM caching component with automatic stale item removal and call rate limiting - this component must be disposed when the driver is closing down. See Dispose for further information.
Inheritance Hierarchy
SystemObject
  ASCOM.UtilitiesCache

Namespace:  ASCOM.Utilities
Assembly:  ASCOM.Cache (in ASCOM.Cache.dll) Version: 3c9121baba46811fe6e53a58a05935662261416d
Syntax
public class Cache : IDisposable

The Cache type exposes the following members.

Constructors
  NameDescription
Public methodCache
Default initialiser that does not assign a TraceLogger unless the cache tracing flag is set.
Public methodCache(TraceLogger)
Inititialiser that takes a reference to the calling application's trace logger. This ensures that trace output will appear in context with the applications's own log messages, making it easier to debug the application.
Top
Properties
  NameDescription
Public propertyPumpMessagesInterval
Get or set the interval, in milliseconds, between calls to Application.DoEvents to pump Windows messages when throttling the cache read rate.
Top
Methods
  NameDescription
Public methodClearCache
Remove all items from the cache.
Public methodDispose
Reset the PC's timing resolution, if changed, and cleanly dispose of the cache's working memory.
Public methodGet(String)
Immediatley retrieve an object from the cache with the given name with no throttling.
Public methodGet(String, Double)
Retrieve an object from the cache with the given name, restricting maximum call frequency to the range 2 to 1000 calls per second if required.
Public methodGetBool(String)
Immediatley retrieve a boolean value from the cache with the given name with no throttling.
Public methodGetBool(String, Double)
Retrieve a boolean value from the cache with the given name, restricting maximum call frequency to the range 2 to 1000 calls per second if required.
Public methodGetDouble(String)
Immediatley retrieve a double value from the cache with the given name with no throttling.
Public methodGetDouble(String, Double)
Retrieve a double value from the cache with the given name, restricting maximum call frequency to the range 2 to 1000 calls per second if required.
Public methodGetInt(String)
Immediatley retrieve an integer value from the cache with the given name with no throttling.
Public methodGetInt(String, Double)
Retrieve an integer value from the cache with the given name, restricting maximum call frequency to the range 2 to 1000 calls per second if required.
Public methodGetString(String)
Immediatley retrieve a string value from the cache with the given name with no throttling.
Public methodGetString(String, Double)
Retrieve a string value from the cache with the given name, restricting maximum call frequency to the range 2 to 1000 calls per second if required.
Public methodRemove
Remove a an item with a specific name from the cache
Public methodSet(String, Object, Double)
Save an object in the cache with the given name and time to live.
Public methodSet(String, Object, Double, Double)
Save an object in the cache with the given name and time to live, restricting maximum call frequency to the range 2 to 1000 calls per second if required.
Public methodSetBool(String, Boolean, Double)
Save a boolean value in the cache with the given name and time to live.
Public methodSetBool(String, Boolean, Double, Double)
Save a boolean value in the cache with the given name and time to live, restricting maximum call frequency to the range 2 to 1000 calls per second if required.
Public methodSetDouble(String, Double, Double)
Save a double value in the cache with the given name and time to live.
Public methodSetDouble(String, Double, Double, Double)
Save a double value in the cache with the given name and time to live, restricting maximum call frequency to the range 2 to 1000 calls per second if required.
Public methodSetInt(String, Int32, Double)
Save an integer value in the cache with the given name and time to live.
Public methodSetInt(String, Int32, Double, Double)
Save an integer value in the cache with the given name and time to live, restricting maximum call frequency to the range 2 to 1000 calls per second if required.
Public methodSetString(String, String, Double)
Save a string value in the cache with the given name and time to live.
Public methodSetString(String, String, Double, Double)
Save a string value in the cache with the given name and time to live, restricting maximum call frequency to the range 2 to 1000 calls per second if required.
Top
Remarks

Astronomy applications are becoming increasingly sophisticated and frequently employ multi-threading techniques that place increasingly high call rate burdens on drivers. Much hardware remains of modest processing capacity and performance can suffer if hardware controllers have to process an excessive number of requests for information and one of the jobs of the driver is to protect the hardware from this kind of situation. Caching is a helpful technique to combat excessive polling of values that don't change frequently and this component provides a conveniently packaged capability to ease driver development.

This cache will store items against specified keys for configurable periods of time and, when an item exceeds its specified retention time, it will automatically be removed by the cache.

Some applications poll at very high rates, so the cache provides an optional rate limiting capability that can delay execution of "set" and "get" methods to enforce a maximum number of actions per second.

The cache "get" methods will either return the requested item, if present, or will throw a NotInCacheException exception, indicating that the driver should poll the hardware and store the value in the cache before returning it to the caller.

Clients using the cache through COM e.g. from scripting languages , Delphi etc. will find that for each group of overloaded methods e.g. GetDouble, only the method with the largest number of parameters is available. This is due to a COM limitation that doesn't allow access to method overloads. .NET clients have access to all overloads.

Code example

using ASCOM.Utilities;
using ASCOM.Utilities.Exceptions;

Class Driver
    const string RIGHT_ASCENSION = "Right Ascension";
    Cache myCache = new Cache();
    ...
    double RightAscension
    {
        get
        {
            try
            {
                return cache.GetDouble(RIGHT_ASCENSION); // Get the RA value from the cache, if present, without limiting the number of reads per second
                // or return cache.GetDouble(RIGHT_ASCENSION, 5.0); // Get the RA value from the cache, if present, limiting the number of reads of this value to 5 per second
            }
            catch (NotInCacheException) // Exception thrown because requested value is not in the cache - so get it from hardware, save to the cache and return the value
            {
                double newRA = ... // Get value from hardware
                cache.SetDouble(RIGHT_ASCENSION, newRA, 1.0); // Save the new value to the cache with a timeout of 1 second
                return newRA;
            }
        }
    }
See Also