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 
26 namespace core
27 {
28 
29 namespace internal
30 {
31 
32 class PersistentStringCacheImpl;
33 
34 } // namespace internal
35 
69 {
70 public:
74  typedef std::unique_ptr<PersistentStringCache> UPtr;
75 
79  struct Data
80  {
84  std::string value;
85 
90  std::string metadata;
91  };
92 
99  //{@
101  PersistentStringCache& operator=(PersistentStringCache const&) = delete;
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 
228  CacheDiscardPolicy discard_policy() const noexcept;
229 
239  PersistentCacheStats stats() const;
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 
521  void invalidate();
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 
543  void clear_stats();
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 
636  void set_handler(CacheEvent events, EventCallback cb);
637 
639 
640 private:
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
Simple pair of value and metadata.
Definition: persistent_string_cache.h:79
An entry was refreshed by a call to touch().
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
CacheEvent
Event types that can be monitored.
Definition: cache_events.h:38
Top-level namespace for core functionality.
Definition: persistent_cache.h:24
STL namespace.
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
std::string value
Stores the value of an entry.
Definition: persistent_string_cache.h:84
An entry was added by a call to put() or get_or_put().
A cache of key-value pairs with persistent storage.
Definition: persistent_string_cache.h:68
An entry was removed by a call to invalidate(), take(), or take_data().
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
std::unique_ptr< PersistentStringCache > UPtr
Definition: persistent_string_cache.h:74
boost::optional< T > Optional
Convenience typedef for nullable values.
Definition: optional.h:33
CacheDiscardPolicy
Indicates the discard policy to make room for entries when the cache is full.
Definition: cache_discard_policy.h:35
Class that provides (read-only) access to cache statistics and settings.
Definition: persistent_cache_stats.h:42