1	<?php
2
3	namespace MediaWiki\Settings\Cache;
4
5	use MediaWiki\Settings\Source\SettingsSource;
6
7	/**
8	* A {@link SettingsSource} that can be cached. It must return a unique
9	* (enough) and deterministic hash key for cache indexing.
10	*
11	* @since 1.38
12	* @stable to implement
13	*/
14	interface CacheableSource extends SettingsSource {
15	/**
16	* Allow the caching layer to attempt to return stale results in the event
17	* that loading from the original source fails.
18	*
19	* Note that allowing stale results will result in cache items being
20	* stored indefinitely regardless of the {@link getExpiryTtl()} value, and
21	* since there is currently no pruning of cache items, it is advised that
22	* sources allowing stale results also implement an immutable
23	* `getHashKey()` based only on constructor arguments.
24	*
25	* @return bool
26	*/
27	public function allowsStaleLoad(): bool;
28
29	/**
30	* Returns the cache TTL (in seconds) for this source.
31	*
32	* @return int
33	*/
34	public function getExpiryTtl(): int;
35
36	/**
37	* Coefficient used in determining early expiration of cached settings to
38	* avoid stampedes.
39	*
40	* Increasing this value will cause the random early election to happen by
41	* a larger margin of lead time before normal expiry, relative to the
42	* cache value's generation duration. Conversely, returning a lesser value
43	* will narrow the margin of lead time, making the cache hold items for
44	* slightly longer but with more likelihood that concurrent regenerations
45	* and set overwrites will occur. Returning <code>0</code> will
46	* effectively disable early expiration, and by extension disable stampede
47	* mitigation altogether.
48	*
49	* A greater value may be suitable if a source has a highly variable
50	* generation duration, but most implementations should simply return
51	* <code>1.0</code>.
52	*
53	* @link https://en.wikipedia.org/wiki/Cache_stampede#Probabilistic_early_expiration
54	* @link https://cseweb.ucsd.edu/~avattani/papers/cache_stampede.pdf
55	*
56	* Optimal Probabilistic Cache Stampede Prevention
57	* Vattani, A.; Chierichetti, F.; Lowenstein, K. (2015), "Optimal
58	* Probabilistic Cache Stampede Prevention" (PDF), Proceedings of the VLDB
59	* Endowment, VLDB, 8 (8): 886–897, doi:10.14778/2757807.2757813, ISSN
60	* 2150-8097 https://cseweb.ucsd.edu/~avattani/papers/cache_stampede.pdf
61	*
62	* @return float
63	*/
64	public function getExpiryWeight(): float;
65
66	/**
67	* Returns a deterministically computed key for use in caching settings
68	* from this source.
69	*
70	* @return string
71	*/
72	public function getHashKey(): string;
73	}