.. contents:: Table of Contents :depth: 3 ================= Infrautils Caches ================= https://git.opendaylight.org/gerrit/#/q/topic:bug/8300 https://www.youtube.com/watch?v=h4HOSRN2aFc Infrautils Caches provide a Cache of keys to values. The implementation of Infrautils Cache API is, typically, backed by established cache frameworks,such as Ehcache, Infinispan, Guava's, Caffeine, ..., imcache, cache2k, ... etc. Problem description =================== Caches are not Maps!. Differences include that a Map persists all elements that are added to it until they are explicitly removed. A Cache on the other hand is generally configured to evict entries automatically, in order to constrain its memory footprint, based on some policy. Another notable difference, enforced by this caching API, is that caches should not be thought of as data structures that you put something in somewhere in your code to get it out of somewhere else. Instead, a Cache is "just a façade" to a CacheFunction's get. This design enforces proper encapsulation, and helps you not to screw up the content of your cache (like you easily can, and usually do, when you use a Map as a cache). Use Cases --------- This feature will support following use cases: * Use case 1: Enable creation of a brand new Cache, based on the passed configuration and policy. * Use case 2: Enable creation of a brand new Cache, based on the passed configuration, with a default policy. * Use case 3: Cache should allow to evict an entry based on the eviction policy. * Use case 4: Cache should allow to put a new entry to the cache. * Use case 5: InfraUtils Cache should expose APIs to retrieve the Cache Policies, Stats, and Fixed Configuration. * Use case 6: InfraUtils Cache should expose APIs to set the Cache Policies, Stats, and Fixed Configuration. Proposed change =============== The proposed feature adds a new module in infrautils called "caches", which will have the following functionalities: * “InfraUtils Cache” has two variants - Cache and CheckedCache. Both are caches of key to values, with CheckedCache having support for cache function which may throw a checked exception. * Cache can be configured to evict entries automatically, in order to constrain its memory footprint, based on some user configured policy. * Cache implementation internally based on Guava Cache will be available(other implementations would be possible, later) * Complete Karaf example with cache usage will be available (see infrautils/caches/sample) * Karaf CLIs will be made available for cache operations YANG changes ------------ N/A Workflow -------- Define a Cache ^^^^^^^^^^^^^^ Applications can define their own Cache, with specified CacheFunction and Policies. Caches can be configured to set the maximum entries and also to enable stats. Define Cache Function ^^^^^^^^^^^^^^^^^^^^^ Cache is "just a façade" to a CacheFunction's get(). When the user defines a CacheFunction for his cache, that will be executed whenever a get() is executed on the cache. Define Anchor ^^^^^^^^^^^^^^ Anchor refers to instance of the class "containing" this Cache. It is used by CacheManagers to display to end-user. Define Cache Id and Description ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Cache id is a short ID for this cache, and description will be a one line human readable description for the cache. Cache Eviction ^^^^^^^^^^^^^^ Cache Eviction Policy is based on the number of entries the cache can hold, which will be set during the cache creation time. Use Cache ^^^^^^^^^ Configuration impact --------------------- N/A Clustering considerations ------------------------- * The current Cache Infra is node local. * Future enhancements can be made by providing clustered backend implementations e.g. Infinispan. Other Infra considerations -------------------------- N.A. Security considerations ----------------------- N.A. Scale and Performance Impact ---------------------------- This feature is aiming at improving the scale and performance of applications by helping to define a CacheFunction for heavy operations. Targeted Release(s) ------------------- Carbon. Known Limitations ----------------- Cache is currently neither distributed (cluster wide) nor transactional." Alternatives ------------ N/A Usage ===== Features to Install ------------------- odl-infrautils-caches odl-infrautils-caches-sample REST API -------- N/A CLI --- cache:clear cache:list cache:policy cacheID policyKey policyValue JAVA API -------- Caches provides the below APIs which can be used by other applications: .. code-block:: bash CacheProvider APIs Cache newCache(CacheConfig cacheConfig, CachePolicy initialPolicy); Cache newCache(CacheConfig cacheConfig); CheckedCache newCheckedCache( CheckedCacheConfig cacheConfig, CachePolicy initialPolicy); CheckedCache newCheckedCache(CheckedCacheConfig cacheConfig); CacheManager APIs BaseCacheConfig getConfig(); CacheStats getStats(); CachePolicy getPolicy(); void setPolicy(CachePolicy newPolicy); void evictAll(); Implementation ============== Assignee(s) ----------- Primary assignee: Work Items ---------- #. spec review. #. caches module bring-up. #. API definitions. #. Cache Policy Implementation. #. Cache and CheckedCache Implementation. #. Backend Implementation #. Add CLI. #. Add UTs. #. Add Documentation. Dependencies ============ Following projects currently depend on InfraUtils: * Netvirt * Genius Testing ======= Unit Tests ---------- Appropriate UTs will be added for the new code coming in once framework is in place. Integration Tests ----------------- N/A CSIT ---- N/A Documentation Impact ==================== This will require changes to Developer Guide. Developer Guide can capture the new set of APIs added by Caches as mentioned in API section. References ========== * https://wiki.opendaylight.org/view/Infrastructure_Utilities:Carbon_Release_Plan