1 thilo.boehm 1.2 //%LICENSE////////////////////////////////////////////////////////////////
  2                 //
  3                 // Licensed to The Open Group (TOG) under one or more contributor license
  4                 // agreements.  Refer to the OpenPegasusNOTICE.txt file distributed with
  5                 // this work for additional information regarding copyright ownership.
  6                 // Each contributor licenses this file to you under the OpenPegasus Open
  7                 // Source License; you may not use this file except in compliance with the
  8                 // License.
  9                 //
 10                 // Permission is hereby granted, free of charge, to any person obtaining a
 11                 // copy of this software and associated documentation files (the "Software"),
 12                 // to deal in the Software without restriction, including without limitation
 13                 // the rights to use, copy, modify, merge, publish, distribute, sublicense,
 14                 // and/or sell copies of the Software, and to permit persons to whom the
 15                 // Software is furnished to do so, subject to the following conditions:
 16                 //
 17                 // The above copyright notice and this permission notice shall be included
 18                 // in all copies or substantial portions of the Software.
 19                 //
 20                 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 21                 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 22 thilo.boehm 1.2 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 23                 // IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 24                 // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 25                 // TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 26                 // SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 27                 //
 28                 //////////////////////////////////////////////////////////////////////////
 29                 //
 30                 //%/////////////////////////////////////////////////////////////////////////////
 31                 #ifndef _SCMOClassCache_H_
 32                 #define _SCMOClassCache_H_
 33                 
 34                 #include <Pegasus/Common/Linkage.h>
 35                 #include <Pegasus/Common/Config.h>
 36                 #include <Pegasus/Common/CIMClass.h>
 37                 #include <Pegasus/Common/ReadWriteSem.h>
 38                 #include <Pegasus/Common/SCMOClass.h>
 39                 
 40                 PEGASUS_NAMESPACE_BEGIN
 41                 
 42                 typedef SCMOClass (*SCMOClassCacheCallbackPtr)(
 43 thilo.boehm 1.2         const CIMNamespaceName& nameSpace,
 44                         const CIMName& className);
 45                 
 46                 //==============================================================================
 47                 //
 48                 // The class cache caches up PEGASUS_SCMO_CLASS_CACHE_SIZE SCMOClass
 49                 // definitions in memory.  To override the default, define
 50                 // PEGASUS_SCMO_CLASS_CACHE_SIZE in your build environment.
 51                 // The functionality to deliver SCMOClass is needed anyway but the cache can be
 52                 // degrated to a pass through functionality.
 53                 // To suppress caching set PEGASUS_SCMO_CLASS_CACHE_SIZE to 0 in your build
 54                 // environment.
 55                 //==============================================================================
 56                 
 57                 #if !defined(PEGASUS_SCMO_CLASS_CACHE_SIZE)
 58                 # define PEGASUS_SCMO_CLASS_CACHE_SIZE 32
 59                 #endif
 60                 
 61                 #if (PEGASUS_SCMO_CLASS_CACHE_SIZE != 0)
 62                 # define PEGASUS_USE_SCMO_CLASS_CACHE
 63                 #endif
 64 thilo.boehm 1.2 
 65                 struct SCMBClassCacheEntry
 66                 {
 67                     // Spin-lock to serialize the access to the entry
 68                     AtomicInt lock;
 69                     // The key to identify the entry
 70                     Uint64    key;
 71                     // Pointer to the cached SCMOClass
 72                     SCMOClass* data;
 73                 };
 74                 
 75                 class PEGASUS_COMMON_LINKAGE SCMOClassCache
 76                 {
 77                 
 78                 public:
 79                 
 80                     /**
 81                      * This function returns the SCMOClass for the given class name and
 82                      * name space.
 83                      * @param ndName The UTF8 encoded name space. '\0' terminated
 84                      * @param nsNameLan The strlen of ndName ( without '\0')
 85 thilo.boehm 1.2      * @param className The UTF8 encoded class name. '\0' terminated
 86                      * @param nsNameLan The strlen of className ( without '\0')
 87                      * @return A pointer to SCMOClass. If the class was not found, an empty
 88                      *         SCMOClass is returned.  This can be checked by using the
 89                      *         SCMOClass.isEmpty() method.
 90                      **/
 91                     SCMOClass getSCMOClass(
 92                         const char* nsName,
 93                         Uint32 nsNameLen,
 94                         const char* className,
 95                         Uint32 classNameLen);
 96                 
 97                     /**
 98                      * Removes the named SCMOClass from the cache.
 99                      * @param cimNameSpace The name space name of the SCMOClass to remove.
100                      * @param cimClassName The class name of the SCMOClass to remove.
101                      **/
102                     void removeSCMOClass(CIMNamespaceName cimNameSpace,CIMName cimClassName);
103                 
104                     /**
105                      * Clears the whole cache.
106 thilo.boehm 1.2      * This should be only done at modification of a class.
107                      * This may invalidate subclass definitions in the cache.
108                      * Since class modification is relatively rare, we just flush the entire
109                      * cache rather than specifically evicting subclass definitions.
110                      **/
111                     void clear();
112                 
113                     /**
114                      * Returns the pointer to an instance of SCMOClassCache.
115                      */
116                     static SCMOClassCache* getInstance();
117                 
118                     /**
119                      * Set the call back function for the SCMOClass to retrieve CIMClasses.
120                      * @param clb The static call back function.
121                      */
122                     void setCallBack(SCMOClassCacheCallbackPtr clb)
123                     {
124                        _resolveCallBack = clb;
125                     }
126                 
127 thilo.boehm 1.2     static void destroy();
128                 
129                 #ifdef PEGASUS_DEBUG
130                 void DisplayCacheStatistics();
131                 #endif
132                 
133                 private:
134                 
135                     // Singleton instance pointer
136                     static SCMOClassCache* _theInstance;
137                 
138                     // The call back function pointer to get CIMClass's
139                     SCMOClassCacheCallbackPtr _resolveCallBack;
140                 
141                 #ifdef PEGASUS_USE_SCMO_CLASS_CACHE
142                 
143                     // The cache array
144                     SCMBClassCacheEntry _theCache[PEGASUS_SCMO_CLASS_CACHE_SIZE];
145                 
146                     // Lock to prevent parallel modifications of the cache.
147                     ReadWriteSem _modifyCacheLock;
148 thilo.boehm 1.2 
149                     // Last successful read index.
150                     Uint32 _lastSuccessIndex;
151                 
152                     // Last successful written cache index.
153                     Uint32 _lastWrittenIndex;
154                 
155                     // Counter of used cache entries.
156                     Uint32 _fillingLevel;
157                 
158                     // Indicator for destruction of the cache.
159                     Boolean _dying;
160                 
161                 #  ifdef PEGASUS_DEBUG
162                     // Statistical data
163                     Uint32 _cacheReadHit;
164                     Uint32 _cacheReadMiss;
165                     Uint32 _cacheRemoveLRU;
166                     AtomicInt _contentionCount;
167                 #  endif
168                 
169 thilo.boehm 1.2     SCMOClassCache()
170                         : _resolveCallBack(NULL),
171                           _lastSuccessIndex(0),
172                           _lastWrittenIndex(PEGASUS_SCMO_CLASS_CACHE_SIZE-1),
173                           _fillingLevel(0),
174                           _dying(false)
175                     {
176                         // intialize the the cache
177                         for (Uint32 i = 0 ; i < PEGASUS_SCMO_CLASS_CACHE_SIZE; i++)
178                         {
179                             _theCache[i].data = 0;
180                             _theCache[i].key = 0;
181                             // set the lock counter to 1 to allow one next user to enter.
182                             _theCache[i].lock.set(1);
183                         }
184                 #  ifdef PEGASUS_DEBUG
185                         // Statistical data
186                         _cacheReadHit = 0;
187                         _cacheReadMiss = 0;
188                         _cacheRemoveLRU = 0;
189                         _contentionCount.set(0);
190 thilo.boehm 1.2 #  endif
191                 
192                     };
193                 
194                     // clean-up cache data
195                     ~SCMOClassCache();
196                 
197                     Uint64 _generateKey(
198                         const char* className,
199                         Uint32 classNameLen,
200                         const char* nameSpaceNameLen,
201                         Uint32 nameSpaceName);
202                 
203                     Boolean _sameSCMOClass(
204                         const char* nsName,
205                         Uint32 nsNameLen,
206                         const char* className,
207                         Uint32 classNameLen,
208                         SCMOClass* theClass);
209                 
210                     SCMOClass _addClassToCache(
211 thilo.boehm 1.2             const char* nsName,
212                             Uint32 nsNameLen,
213                             const char* className,
214                             Uint32 classNameLen,
215                             Uint64 theKey);
216                 
217                 
218                     /**
219                      * Get a lock on a cache entry.
220                      * @return true if the lock was optained
221                      *         false if the lock was NOT optained, give up !!!
222                      **/
223                     Boolean _lockEntry(Uint32 index);
224                 
225                     void _unlockEntry(Uint32 index)
226                     {
227                         // set the lock counter to 1 to allow one next user to enter
228                         // the critical section.
229                         _theCache[index].lock.set(1);
230                 
231                     };
232 thilo.boehm 1.2 #endif
233                 };
234                 
235                 PEGASUS_NAMESPACE_END
236                 
237                 #endif