This file is indexed.

/usr/include/kshareddatacache.h is in kdelibs5-dev 4:4.8.4-4+deb7u1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
/*
 * This file is part of the KDE project.
 * Copyright © 2010 Michael Pyne <mpyne@kde.org>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License version 2 as published by the Free Software Foundation.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public License
 * along with this library; see the file COPYING.LIB.  If not, write to
 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
 */

#ifndef KSHAREDDATACACHE_H
#define KSHAREDDATACACHE_H

#include <kdecore_export.h>

class QString;
class QByteArray;

/**
 * @brief A simple data cache which uses shared memory to quickly access data
 * stored on disk.
 *
 * This class is meant to be used with KImageCache and similar classes but can
 * be used directly if used with care.
 *
 * Example usage:
 *
 * @code
 * QString loadTranslatedDocument(KSharedDataCache *cache) {
 *
 *   // Find the data
 *   QByteArray document;
 *
 *   if (!cache->find("translated-doc-template", &document)) {
 *     // Entry is not cached, manually generate and then add to cache.
 *     document = translateDocument(globalTemplate());
 *     cache->insert(document);
 *   }
 *
 *   // Don't forget to encode/decode properly
 *   return QString::fromUtf8(document);
 * }
 * @endcode
 *
 * @author Michael Pyne <mpyne@kde.org>
 * @see KImageCache
 * @since 4.5
 */
class KDECORE_EXPORT KSharedDataCache
{
public:
    /**
     * Attaches to a shared cache, creating it if necessary. If supported, this
     * data cache will be shared across all processes using this cache (with
     * subsequent memory savings).  If shared memory is unsupported or a
     * failure occurs, caching will still be supported, but only in the same
     * process, and only using the same KSharedDataCache object.
     *
     * @param cacheName Name of the cache to use/share.
     * @param defaultCacheSize Amount of data to be able to store, in bytes. The
     *   actual size will be slightly larger on disk due to accounting
     *   overhead.  If the cache already existed then it <em>will not</em> be
     *   resized. For this reason you should specify some reasonable size.
     * @param expectedItemSize The average size of an item that would be stored
     *   in the cache, in bytes. Choosing an average size of zero bytes causes
     *   KSharedDataCache to use whatever it feels is the best default for the
     *   system.
     */
    KSharedDataCache(const QString &cacheName,
                     unsigned defaultCacheSize,
                     unsigned expectedItemSize = 0);
    ~KSharedDataCache();

    enum EvictionPolicy
    {
        // The default value for data in our shared memory will be 0, so it is
        // important that whatever we want for the default value is also 0.
        NoEvictionPreference = 0,
        EvictLeastRecentlyUsed,
        EvictLeastOftenUsed,
        EvictOldest
    };

    /**
     * @return The removal policy in use by the shared cache.
     * @see EvictionPolicy
     */
    EvictionPolicy evictionPolicy() const;

    /**
     * Sets the entry removal policy for the shared cache to
     * @p newPolicy. The default is EvictionPolicy::NoEvictionPreference.
     *
     * @see EvictionPolicy
     */
    void setEvictionPolicy(EvictionPolicy newPolicy);

    /**
     * Attempts to insert the entry @p data into the shared cache, named by
     * @p key, and returns true only if successful.
     *
     * Note that even if the insert was successful, that the newly added entry
     * may be evicted by other processes contending for the cache.
     */
    bool insert(const QString &key, const QByteArray &data);

    /**
     * Returns the data in the cache named by @p key (even if it's some other
     * process's data named with the same key!), stored in @p destination. If there is
     * no entry named by @p key then @p destination is left unchanged. The return value
     * is used to tell what happened.
     *
     * If you simply want to verify whether an entry is present in the cache then
     * see contains().
     *
     * @param key The key to find in the cache.
     * @param destination Is set to the value of @p key in the cache if @p key is
     *                    present, left unchanged otherwise.
     * @return true if @p key was present in the cache (@p destination will also be
     *         updated), false if @p key was not present (@p destination will be
     *         unchanged).
     */
    bool find(const QString &key, QByteArray *destination) const;

    /**
     * Removes all entries from the cache.
     */
    void clear();

    /**
     * Removes the underlying file from the cache. Note that this is *all* that this
     * function does. The shared memory segment is still attached and will still contain
     * all the data until all processes currently attached remove the mapping.
     *
     * In order to remove the data see clear().
     */
    static void deleteCache(const QString &cacheName);

    /**
     * Returns true if the cache currently contains the image for the given
     * filename.
     *
     * NOTE: Calling this function is threadsafe, but it is in general not
     * possible to guarantee the image stays cached immediately afterwards,
     * so if you need the result use find().
     */
    bool contains(const QString &key) const;

    /**
     * Returns the usable cache size in bytes. The actual amount of memory
     * used will be slightly larger than this to account for required
     * accounting overhead.
     */
    unsigned totalSize() const;

    /**
     * Returns the amount of free space in the cache, in bytes. Due to
     * implementation details it is possible to still not be able to fit an
     * entry in the cache at any given time even if it is smaller than the
     * amount of space remaining.
     */
    unsigned freeSize() const;

    /**
     * @return The shared timestamp of the cache. The interpretation of the
     *         timestamp returned is up to the application. KSharedDataCache
     *         will initialize the timestamp to the time returned by @c time(2)
     *         on cache creation, but KSharedDataCache will not touch the
     *         timestamp again.
     * @see setTimestamp()
     * @since 4.6
     */
    unsigned timestamp() const;

    /**
     * Sets the shared timestamp of the cache. Timestamping is supported to
     * allow applications to more effectively "version" the data stored in the
     * cache. However, the timestamp is shared with <em>all</em> applications
     * using the cache so you should always be prepared for invalid
     * timestamps.
     *
     * When the cache is first created (note that this is different from
     * attaching to an existing shared cache on disk), the cache timestamp is
     * initialized to the time returned by @c time(2). KSharedDataCache will
     * not update the timestamp again, it is only updated through this method.
     *
     * Example:
     * @code
     * QImage loadCachedImage(const QString &key)
     * {
     *     // Check timestamp
     *     if (m_sharedCache->timestamp() < m_currentThemeTimestamp) {
     *         // Cache is stale, clean it out.
     *         m_sharedCache->clear();
     *         m_sharedCache->setTimestamp(m_currentThemeTimestamp);
     *     }
     *
     *     // Check cache and load image as usual...
     * }
     * @endcode
     *
     * @param newTimestamp The new timestamp to mark the shared cache with.
     * @see timestamp()
     * @since 4.6
     */
    void setTimestamp(unsigned newTimestamp);

private:
    class Private;
    Private *d;
};

#endif