persistent-cache-cpp
persistent_string_cache.h
Go to the documentation of this file.
1/*
2 * Copyright (C) 2015 Canonical Ltd.
3 *
4 * This program is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License version 3 as
6 * published by the Free Software Foundation.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU Lesser General Public License for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this program. If not, see <http://www.gnu.org/licenses/>.
15 *
16 * Authored by: Michi Henning <michi.henning@canonical.com>
17 */
18
19#pragma once
20
22#include <core/cache_events.h>
23#include <core/optional.h>
25
26namespace core
27{
28
29namespace internal
30{
31
32class PersistentStringCacheImpl;
33
34} // namespace internal
35
69{
70public:
74 typedef std::unique_ptr<PersistentStringCache> UPtr;
75
79 struct Data
80 {
84 std::string value;
85
90 std::string metadata;
91 };
92
99 //{@
102
106
111
115 //{@
116
140 static UPtr open(std::string const& cache_path, int64_t max_size_in_bytes, CacheDiscardPolicy policy);
141
147 static UPtr open(std::string const& cache_path);
148
150
154 //{@
155
163 Optional<std::string> get(std::string const& key) const;
164
173 Optional<Data> get_data(std::string const& key) const;
174
183 Optional<std::string> get_metadata(std::string const& key) const;
184
193 bool contains_key(std::string const& key) const;
194
200 int64_t size() const noexcept;
201
207 int64_t size_in_bytes() const noexcept;
208
214 int64_t max_size_in_bytes() const noexcept;
215
222 int64_t disk_size_in_bytes() const;
223
229
240
242
246 //{@
247
265 bool put(std::string const& key,
266 std::string const& value,
267 std::chrono::time_point<std::chrono::system_clock> expiry_time = std::chrono::system_clock::time_point());
268
295 bool put(std::string const& key,
296 char const* value,
297 int64_t size,
298 std::chrono::time_point<std::chrono::system_clock> expiry_time = std::chrono::system_clock::time_point());
299
315 bool put(std::string const& key,
316 std::string const& value,
317 std::string const& metadata,
318 std::chrono::time_point<std::chrono::system_clock> expiry_time = std::chrono::system_clock::time_point());
319
345 bool put(std::string const& key,
346 char const* value,
347 int64_t value_size,
348 char const* metadata,
349 int64_t metadata_size,
350 std::chrono::time_point<std::chrono::system_clock> expiry_time = std::chrono::system_clock::time_point());
351
355 typedef std::function<void(std::string const& key, PersistentStringCache& cache)> Loader;
356
377 Optional<std::string> get_or_put(std::string const& key, Loader const& load_func);
378
399 Optional<Data> get_or_put_data(std::string const& key, Loader const& load_func);
400
416 bool put_metadata(std::string const& key, std::string const& metadata);
417
442 bool put_metadata(std::string const& key, char const* metadata, int64_t size);
443
453 Optional<std::string> take(std::string const& key);
454
465 Optional<Data> take_data(std::string const& key);
466
476 bool invalidate(std::string const& key);
477
484 void invalidate(std::vector<std::string> const& keys);
485
495 template<typename It>
496 void invalidate(It begin, It end)
497 {
498 std::vector<std::string> keys;
499 while (begin < end)
500 {
501 keys.push_back(*begin++);
502 }
503 invalidate(keys);
504 }
505
512 void invalidate(std::initializer_list<std::string> const& keys);
513
522
536 bool touch(
537 std::string const& key,
538 std::chrono::time_point<std::chrono::system_clock> expiry_time = std::chrono::system_clock::time_point());
539
544
558 void resize(int64_t size_in_bytes);
559
570 void trim_to(int64_t used_size_in_bytes);
571
579 void compact();
580
582
595 //{@
596
612 typedef std::function<void(std::string const& key, CacheEvent ev, PersistentCacheStats const& stats)> EventCallback;
613
637
639
640private:
641 // @cond
642 PersistentStringCache(std::string const& cache_path, int64_t max_size_in_bytes, CacheDiscardPolicy policy);
643 PersistentStringCache(std::string const& cache_path);
644
645 std::unique_ptr<internal::PersistentStringCacheImpl> p_;
646 // @endcond
647};
648
649} // namespace core
Class that provides (read-only) access to cache statistics and settings.
Definition persistent_cache_stats.h:43
A cache of key-value pairs with persistent storage.
Definition persistent_string_cache.h:69
void invalidate(std::initializer_list< std::string > const &keys)
Atomically removes the specified entries from the cache.
void clear_stats()
Resets all statistics counters.
PersistentCacheStats stats() const
Returns statistics for the cache.
CacheDiscardPolicy discard_policy() const noexcept
Returns the discard policy of the cache.
Optional< Data > get_data(std::string const &key) const
Returns the data for an entry in the cache, provided the entry has not expired.
bool touch(std::string const &key, std::chrono::time_point< std::chrono::system_clock > expiry_time=std::chrono::system_clock::time_point())
Updates the access time of an entry.
bool contains_key(std::string const &key) const
Tests if an (unexpired) entry is in the cache.
void set_handler(CacheEvent events, EventCallback cb)
Installs a handler for one or more events.
PersistentStringCache & operator=(PersistentStringCache const &)=delete
int64_t max_size_in_bytes() const noexcept
Returns the maximum size of the cache in bytes.
int64_t disk_size_in_bytes() const
Returns an estimate of the disk space consumed by the cache.
bool put_metadata(std::string const &key, std::string const &metadata)
Adds or replaces the metadata for an entry.
void resize(int64_t size_in_bytes)
Changes the maximum size of the cache.
void trim_to(int64_t used_size_in_bytes)
Expires entries.
int64_t size() const noexcept
Returns the number of entries in the cache.
Optional< Data > take_data(std::string const &key)
Removes an entry and returns its value and metadata.
Optional< std::string > get(std::string const &key) const
Returns the value of an entry in the cache, provided the entry has not expired.
int64_t size_in_bytes() const noexcept
Returns the number of bytes consumed by entries in the cache.
Optional< Data > get_or_put_data(std::string const &key, Loader const &load_func)
Atomically retrieves or stores a cache entry.
Optional< std::string > take(std::string const &key)
Removes an entry and returns its value.
PersistentStringCache(PersistentStringCache const &)=delete
static UPtr open(std::string const &cache_path, int64_t max_size_in_bytes, CacheDiscardPolicy policy)
Creates or opens a PersistentStringCache.
static UPtr open(std::string const &cache_path)
Opens an existing PersistentStringCache.
void invalidate()
Deletes all entries from the cache.
Optional< std::string > get_or_put(std::string const &key, Loader const &load_func)
Atomically retrieves or stores a cache entry.
PersistentStringCache(PersistentStringCache &&)
Optional< std::string > get_metadata(std::string const &key) const
Returns the metadata for an entry in the cache, provided the entry has not expired.
void compact()
Compacts the database.
std::function< void(std::string const &key, PersistentStringCache &cache)> Loader
Function called by the cache to load an entry after a cache miss.
Definition persistent_string_cache.h:355
std::unique_ptr< PersistentStringCache > UPtr
Definition persistent_string_cache.h:74
PersistentStringCache & operator=(PersistentStringCache &&)
std::function< void(std::string const &key, CacheEvent ev, PersistentCacheStats const &stats)> EventCallback
The type of a handler function.
Definition persistent_string_cache.h:612
Top-level namespace for core functionality.
Definition cache_codec.h:24
CacheDiscardPolicy
Indicates the discard policy to make room for entries when the cache is full.
Definition cache_discard_policy.h:36
CacheEvent
Event types that can be monitored.
Definition cache_events.h:39
@ put
An entry was added by a call to put() or get_or_put().
boost::optional< T > Optional
Convenience typedef for nullable values.
Definition optional.h:39
Simple pair of value and metadata.
Definition persistent_string_cache.h:80
std::string value
Stores the value of an entry.
Definition persistent_string_cache.h:84
std::string metadata
Stores the metadata of an entry. If no metadata exists for an entry, metadata is returned as the empt...
Definition persistent_string_cache.h:90