Share via

Expiration and Eviction (Velocity)

  • Article

[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

Cached objects do not remain in memory permanently in Microsoft project code named "Velocity." In addition to being explicitly removed from cache by use of the Remove method, cached objects may also expire or be evicted by the cache cluster.

Expiration

Cache expiration allows the cache cluster to automatically remove cached objects from the cache. When using the Put or Add methods, an optional object time-out value can be set for the particular cached object that will determine how many minutes it will reside in cache. If the object time-out value is not provided at the time the object is cached, the values specified in the cluster configuration settings for the named cache are used to determine the lifetime of the object in cache.

When cached objects are locked for the purposes of concurrency, they will not be removed from cache even if they are past their expiration. As soon as they are unlocked, they will be immediately removed from cache if past their expiration.

To prevent instant removal when you unlock expired objects, the Unlock method also supports extending the expiration of the cached object. For more information about the supported concurrency models and methods, see Concurrency Models (Velocity) and Concurrency Methods (Velocity).

Local Cache Invalidation

Once objects are downloaded to local cache, your application continues to use those objects until they are invalidated, regardless of whether those objects are updated by another client on the cache cluster. For this reason, it is best to use local cache for data that changes less frequently. There are two types of invalidation for local cache: timeout-based invalidation and notification-based invalidation.

Timeout-based Invalidation

Once objects are downloaded to local cache, they stay there until they reach the object timeout value specified in the client configuration settings (ttlValue in the app.config file). Once they reach this time-out value, objects are invalidated so that the object can be refreshed from the cache cluster the next time that it is requested.

Note

Your application continues to use objects stored in the local cache until they reach the end of their lifetimes, regardless of whether those objects are updated by another client on the cache cluster. For this reason, it is best to use local cache for data that changes infrequently.

To specify timeout-based cache invalidation for local cache set the sync attribute in the localCache element to TTLBased. For more information about application configuration settings, see Application Configuration Settings (Velocity).

Notification-based Invalidation

If local cache is enabled on a routing client, you may also use cache notifications to automatically invalidate your locally cached objects. By shortening the lifetime of those objects on an "as needed" basis, you can reduce the possibility that your application is using stale data.

When you use cache notifications, your application checks with the cache cluster on a regular interval to see if any new notifications are available. This interval, called the polling interval, is every 300 seconds by default. The polling interval is specified in units of seconds in the application configuration settings. To specify a specific interval, use can use the pollInterval attribute of the clientNotifications element in the application configuration file. You can also specify a specific polling interval programmatically with the DataCacheFactory constructor.

Note

In order for your application to use notifications you will need to enable them on a named cache. Use the notificationsEnabled parameter with the New-Cache or Set-CacheConfig commands. For more information, see Cache Administration with PowerShell (Velocity).

To specify notification-based cache invalidation for local cache set the sync attribute in the localCache element to NotificationsBased. When notification-based invalidation is chosen for local cache, any specified timeout value is ignored. For more information, see How to: Enable Local Cache (XML) (Velocity).

Eviction

In order to maintain the memory capacity available for cache on each cache host, "Velocity" supports least recently used (LRU) eviction. Thresholds, referred to as watermarks, are used to make sure that memory is evenly distributed across all cache hosts in the cluster.

When the memory consumption of the cache host service on a cache server exceeds the low watermark threshold, "Velocity" starts evicting objects that have already expired.

When memory consumption exceeds the high watermark threshold, objects are evicted out of memory, regardless of whether they have expired or not, until memory consumption goes back down to the low watermark. Subsequently cached objects may be rerouted to other hosts in order to maintain an optimal distribution of memory.

Specifying Expiration and Eviction Settings

Expiration and eviction behavior are configured at the named cache level in the cluster configuration settings. These cache-level settings can be configured with the PowerShell-based cache administration tool. For more information, see Cache Administration with PowerShell (Velocity).

Additionally, the following methods allow you to override the default settings that are in the cache:

  • The CreateRegion method allows you to enable or disable eviction for objects stored in the region.

  • The Add and Put methods provide overloads that allow you to specify an expiration timeout value only for the object you add to the cache.

  • The PutAndUnlock and Unlock methods provide overloads that allow you to extend an object's expiration after unlocking it.

  • The ResetObjectTimeout method allows you to explicitly extend an object's lifetime, overriding the expiration settings of the cache.

Regardless of the expiration or eviction settings, if a cache cluster is restarted, all objects in the cache are flushed. Your application code must reload the cache from a data source if the data is not found in the cache. This is often referred to as a cache-aside programming pattern.

See Also

Concepts

General Concept Models (Velocity)
Cache Clients and Local Cache (Velocity)
Concurrency Models (Velocity)
High Availability (Velocity)
Data Classification (Velocity)

Other Resources

Programming Guide (Velocity)
Administration Guide (Velocity)