2
* Copyright (C) 2015 Canonical Ltd.
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.
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.
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/>.
16
* Authored by: Michi Henning <michi.henning@canonical.com>
21
#include <core/cache_discard_policy.h>
33
class PersistentStringCacheImpl;
34
class PersistentStringCacheStats;
36
} // namespace internal
39
\brief Class that provides (read-only) access to cache statistics and settings.
42
class PersistentCacheStats
45
/** @name Construction, Copy and Assignment
46
Copy and assignment have the usual value semantics.
47
The default constructor creates an instance with
48
an empty cache path, `lru_only` policy, and the
49
remaining values set to zero.
52
PersistentCacheStats();
53
PersistentCacheStats(PersistentCacheStats const&);
54
PersistentCacheStats(PersistentCacheStats&&) noexcept;
55
PersistentCacheStats& operator=(PersistentCacheStats const&);
56
PersistentCacheStats& operator=(PersistentCacheStats&&);
59
// Accessors instead of data members for ABI stability.
65
\brief Returns the path to the cache directory.
67
std::string cache_path() const;
70
\brief Returns the discard policy (`lru_only` or `lru_ttl`).
72
CacheDiscardPolicy policy() const noexcept;
75
\brief Returns the number of entries (including expired ones).
77
int64_t size() const noexcept;
80
\brief Returns the size of all entries (including expired ones).
82
int64_t size_in_bytes() const noexcept;
85
\brief Returns the maximum size of the cache.
87
int64_t max_size_in_bytes() const noexcept;
90
\brief Returns the number of hits since the statistics were last reset.
92
int64_t hits() const noexcept;
95
\brief Returns the number of misses since the statistics were last reset.
97
int64_t misses() const noexcept;
100
\brief Returns the number of consecutive hits since the last miss.
102
int64_t hits_since_last_miss() const noexcept;
105
\brief Returns the number of consecutive misses since the last hit.
107
int64_t misses_since_last_hit() const noexcept;
110
\brief Returns the largest number of consecutive hits.
112
int64_t longest_hit_run() const noexcept;
115
\brief Returns the largest number of consecutive misses.
117
int64_t longest_miss_run() const noexcept;
120
\brief Returns the number of entries that were evicted due to being expired.
122
int64_t ttl_evictions() const noexcept;
125
\brief Returns the number of entries that were evicted due to being
128
int64_t lru_evictions() const noexcept;
131
\brief Returns the timestamp of the most recent hit.
133
std::chrono::system_clock::time_point most_recent_hit_time() const noexcept;
136
\brief Returns the timestamp of the most recent miss.
138
std::chrono::system_clock::time_point most_recent_miss_time() const noexcept;
141
\brief Returns the time of the longest hit run.
143
std::chrono::system_clock::time_point longest_hit_run_time() const noexcept;
146
\brief Returns the time of the longest miss run.
148
std::chrono::system_clock::time_point longest_miss_run_time() const noexcept;
151
\brief Histogram of the size distribution of cache entries.
153
The histogram uses a logarithmic scale and contains the number of entries in
154
the cache, with entries grouped by size into a number of bins as follows:
156
Index | Entry size in bytes
157
----- | -------------------
174
72 | 900,000,000..999,999,999
177
Index 0 contains the number of entries < 10 bytes. Thereafter, the histogram
178
contains 9 bins for each power of 10, plus a final bin at index 73 that contains
179
the number of entries ≥ 10<sup>9</sup> bytes.
181
typedef std::vector<uint32_t> Histogram;
184
\brief Lower and upper bounds for the bins in the histogram.
186
Each pair contains the lower and upper (inclusive) bound of
187
the corresponding bin of the values returned by histogram().
189
typedef std::vector<std::pair<int32_t, int32_t>> HistogramBounds;
192
\brief The number of bins in a histogram.
194
static constexpr unsigned NUM_BINS = 74;
197
\brief Returns a histogram for the entries in the cache.
199
Histogram const& histogram() const noexcept;
202
\brief Returns the bounds for each bin a histogram.
204
This method returns the same vector each time; it is provided
205
as a convenience method to make it easier to add labels to a
206
histogram for display. The returned pairs use inclusive ranges,
207
that is, `pair.second` is the largest possible size of the bin.
209
static HistogramBounds const& histogram_bounds() noexcept;
214
PersistentCacheStats(std::shared_ptr<core::internal::PersistentStringCacheStats> const& p) noexcept;
216
// We store a shared_ptr for efficiency. When the caller
217
// retrieves the stats, we set p_ to point at the PersistentStringCacheStats
218
// inside the cache. If the caller makes a copy or assigns,
219
// We create a new instance, to provide value semantics. This means
220
// that we don't have to copy all of the stats each time the caller
222
std::shared_ptr<internal::PersistentStringCacheStats const> p_;
223
bool internal_; // True if p_ points at the internal instance.
226
friend class internal::PersistentStringCacheImpl; // For access to constructor