BlobCache.h revision 90f43dce840b2a815426b6bfcdbe5f92358ab956 
1/*
2 ** Copyright 2011, The Android Open Source Project
3 **
4 ** Licensed under the Apache License, Version 2.0 (the "License");
5 ** you may not use this file except in compliance with the License.
6 ** You may obtain a copy of the License at
7 **
8 **     http://www.apache.org/licenses/LICENSE-2.0
9 **
10 ** Unless required by applicable law or agreed to in writing, software
11 ** distributed under the License is distributed on an "AS IS" BASIS,
12 ** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 ** See the License for the specific language governing permissions and
14 ** limitations under the License.
15 */
16
17#ifndef ANDROID_BLOB_CACHE_H
18#define ANDROID_BLOB_CACHE_H
19
20#include <stddef.h>
21
22#include <utils/RefBase.h>
23#include <utils/SortedVector.h>
24#include <utils/threads.h>
25
26namespace android {
27
28// A BlobCache is an in-memory cache for binary key/value pairs.  A BlobCache
29// does NOT provide any thread-safety guarantees.
30//
31// The cache contents can be serialized to a file and reloaded in a subsequent
32// execution of the program. This serialization is non-portable and should only
33// be loaded by the device that generated it.
34class BlobCache : public RefBase {
35public:
36
37    // Create an empty blob cache. The blob cache will cache key/value pairs
38    // with key and value sizes less than or equal to maxKeySize and
39    // maxValueSize, respectively. The total combined size of ALL cache entries
40    // (key sizes plus value sizes) will not exceed maxTotalSize.
41    BlobCache(size_t maxKeySize, size_t maxValueSize, size_t maxTotalSize);
42
43    // set inserts a new binary value into the cache and associates it with the
44    // given binary key.  If the key or value are too large for the cache then
45    // the cache remains unchanged.  This includes the case where a different
46    // value was previously associated with the given key - the old value will
47    // remain in the cache.  If the given key and value are small enough to be
48    // put in the cache (based on the maxKeySize, maxValueSize, and maxTotalSize
49    // values specified to the BlobCache constructor), then the key/value pair
50    // will be in the cache after set returns.  Note, however, that a subsequent
51    // call to set may evict old key/value pairs from the cache.
52    //
53    // Preconditions:
54    //   key != NULL
55    //   0 < keySize
56    //   value != NULL
57    //   0 < valueSize
58    void set(const void* key, size_t keySize, const void* value,
59            size_t valueSize);
60
61    // The get function retrieves from the cache the binary value associated
62    // with a given binary key.  If the key is present in the cache then the
63    // length of the binary value associated with that key is returned.  If the
64    // value argument is non-NULL and the size of the cached value is less than
65    // valueSize bytes then the cached value is copied into the buffer pointed
66    // to by the value argument.  If the key is not present in the cache then 0
67    // is returned and the buffer pointed to by the value argument is not
68    // modified.
69    //
70    // Note that when calling get multiple times with the same key, the later
71    // calls may fail, returning 0, even if earlier calls succeeded.  The return
72    // value must be checked for each call.
73    //
74    // Preconditions:
75    //   key != NULL
76    //   0 < keySize
77    //   0 <= valueSize
78    size_t get(const void* key, size_t keySize, void* value, size_t valueSize);
79
80private:
81    // Copying is disallowed.
82    BlobCache(const BlobCache&);
83    void operator=(const BlobCache&);
84
85    // A random function helper to get around MinGW not having nrand48()
86    long int blob_random();
87
88    // clean evicts a randomly chosen set of entries from the cache such that
89    // the total size of all remaining entries is less than mMaxTotalSize/2.
90    void clean();
91
92    // isCleanable returns true if the cache is full enough for the clean method
93    // to have some effect, and false otherwise.
94    bool isCleanable() const;
95
96    // A Blob is an immutable sized unstructured data blob.
97    class Blob : public RefBase {
98    public:
99        Blob(const void* data, size_t size, bool copyData);
100        ~Blob();
101
102        bool operator<(const Blob& rhs) const;
103
104        const void* getData() const;
105        size_t getSize() const;
106
107    private:
108        // Copying is not allowed.
109        Blob(const Blob&);
110        void operator=(const Blob&);
111
112        // mData points to the buffer containing the blob data.
113        const void* mData;
114
115        // mSize is the size of the blob data in bytes.
116        size_t mSize;
117
118        // mOwnsData indicates whether or not this Blob object should free the
119        // memory pointed to by mData when the Blob gets destructed.
120        bool mOwnsData;
121    };
122
123    // A CacheEntry is a single key/value pair in the cache.
124    class CacheEntry {
125    public:
126        CacheEntry();
127        CacheEntry(const sp<Blob>& key, const sp<Blob>& value);
128        CacheEntry(const CacheEntry& ce);
129
130        bool operator<(const CacheEntry& rhs) const;
131        const CacheEntry& operator=(const CacheEntry&);
132
133        sp<Blob> getKey() const;
134        sp<Blob> getValue() const;
135
136        void setValue(const sp<Blob>& value);
137
138    private:
139
140        // mKey is the key that identifies the cache entry.
141        sp<Blob> mKey;
142
143        // mValue is the cached data associated with the key.
144        sp<Blob> mValue;
145    };
146
147    // mMaxKeySize is the maximum key size that will be cached. Calls to
148    // BlobCache::set with a keySize parameter larger than mMaxKeySize will
149    // simply not add the key/value pair to the cache.
150    const size_t mMaxKeySize;
151
152    // mMaxValueSize is the maximum value size that will be cached. Calls to
153    // BlobCache::set with a valueSize parameter larger than mMaxValueSize will
154    // simply not add the key/value pair to the cache.
155    const size_t mMaxValueSize;
156
157    // mMaxTotalSize is the maximum size that all cache entries can occupy. This
158    // includes space for both keys and values. When a call to BlobCache::set
159    // would otherwise cause this limit to be exceeded, either the key/value
160    // pair passed to BlobCache::set will not be cached or other cache entries
161    // will be evicted from the cache to make room for the new entry.
162    const size_t mMaxTotalSize;
163
164    // mTotalSize is the total combined size of all keys and values currently in
165    // the cache.
166    size_t mTotalSize;
167
168    // mRandState is the pseudo-random number generator state. It is passed to
169    // nrand48 to generate random numbers when needed.
170    unsigned short mRandState[3];
171
172    // mCacheEntries stores all the cache entries that are resident in memory.
173    // Cache entries are added to it by the 'set' method.
174    SortedVector<CacheEntry> mCacheEntries;
175};
176
177}
178
179#endif // ANDROID_BLOB_CACHE_H
180