8000 document cache pruning functionality · symfony/symfony-docs@ea29252 · GitHub
[go: up one dir, main page]
Skip to content

Commit ea29252

Browse files
robfrawleyrobfrawley
committed
document cache pruning functionality
- note the addition of PruneableInterface - note the variouse, concrete PruneableInterface::prune() implementations in ChainAdapter, FilesystemAdapter, PdoAdapter, PhpFilesAdapter, ChainCache, FilesystemCache, PdoCache, PhpFilesCache, and TagAwareAdapter. - note the addition of CachePoolPruneCommand, invokable via cache:pool:prune. This command iterates over all services tagged cache.pool and calls the PruneableInterface::prune() method on those that implement PruneableInterface - rewording of some adapter text for clarity - additional note blocks for all caches that implement PruneableInterface - addition of prune() description and usage example on the chain adapter - addition of a tip about achieving better performance with the filesystem adapter by utilizing tmpfs or another ram disk solution - fix for an incorrect use statement in the PHP array cache adapter code example - addition of documentation page for PHP files adapter - addition of a "pruning cache items" explanation and example on the main cache pools page
1 parent 29cae98 commit ea29252

9 files changed

+222
-34
lines changed

‎components/cache/adapters/apcu_adapter.rst

Lines changed: 10 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,17 @@
77
APCu Cache Adapter
88
==================
99

10-
This adapter is a high-performance, shared memory cache. It can increase the
11-
application performance very significantly because the cache contents are
12-
stored in the shared memory of your server, a component that is much faster than
13-
others, such as the filesystem.
10+
This adapter is a high-performance, shared memory cache. It can *significantly* increase
11+
an application's performance, as its cache contents are stored in shared memory, a component
12+
appreciably faster than many others, such as the filesystem.
1413

1514
.. caution::
1615

1716
**Requirement:** The `APCu extension`_ must be installed and active to use
1817
this adapter.
1918

20-
This adapter can be provided an optional namespace string as its first parameter, a
21-
default cache lifetime as its second parameter, and a version string as its third
22-
parameter::
19+
The ApcuAdapter can optionally be provided a namespace, default cache lifetime, and cache
20+
items version string as constructor arguments::
2321

2422
use Symfony\Component\Cache\Adapter\ApcuAdapter;
2523

@@ -40,15 +38,13 @@ parameter::
4038

4139
.. caution::
4240

43-
It is *not* recommended to use this adapter when performing a large number of
44-
write and delete operations, as these operations result in fragmentation of the
45-
APCu memory, resulting in *significantly* degraded performance.
41+
Use of this adapter is discouraged in write/delete heavy workloads, as these
42+
operations cause memory fragmentation that results in significantly degraded performance.
4643

4744
.. tip::
4845

49-
Note that this adapter's CRUD operations are specific to the PHP SAPI it is running
50-
under. This means adding a cache item using the CLI will not result in the item
51-
appearing under FPM. Likewise, deletion of an item using CGI will not result in the
52-
item being deleted under the CLI.
46+
This adapter's CRUD operations are specific to the PHP SAPI it is running under. This
47+
means cache operations (such as additions, deletions, etc) using the CLI will not be
48+
available under the FPM or CGI SAPIs.
5349

5450
.. _`APCu extension`: https://pecl.php.net/package/APCu

‎components/cache/adapters/chain_adapter.rst

Lines changed: 32 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,18 @@
22
single: Cache Pool
33
single: Chain Cache
44

5+
.. _component-cache-chain-adapter:
6+
57
Chain Cache Adapter
68
===================
79

8-
This adapter allows to combine any number of the other available cache adapters.
9-
Cache items are fetched from the first adapter which contains them and cache items are
10-
saved in all the given adapters. This offers a simple way of creating a layered cache.
10+
This adapter allows combining any number of the other
11+
:ref:`available cache adapters <component-cache-creating-cache-pools>`. Cache items are
12+
fetched from the first adapter containing them and cache items are saved to all the
13+
given adapters. This exposes a simple and efficient method for creating a layeted cache.
1114

12-
This adapter expects an array of adapters as its first parameter, and optionally a
13-
maximum cache lifetime as its second parameter::
15+
The ChainAdapter must be provided an array of adapters and optionally a maximum cache
16+
lifetime as its constructor arguments::
1417

1518
use Symfony\Component\Cache\Adapter\ApcuAdapter;
1619

@@ -26,7 +29,7 @@ maximum cache lifetime as its second parameter::
2629
.. note::
2730

2831
When an item is not found in the first adapter but is found in the next ones, this
29-
adapter ensures that the fetched item is saved in all the adapters where it was
32+
adapter ensures that the fetched item is saved to all the adapters where it was
3033
previously missing.
3134

3235
The following example shows how to create a chain adapter instance using the fastest and
@@ -41,3 +44,26 @@ slowest storage engines, :class:`Symfony\\Component\\Cache\\Adapter\\ApcuAdapter
4144
new ApcuAdapter(),
4245
new FilesystemAdapter(),
4346
));
47+
48+
When calling this adapter's :method:`Symfony\\Component\\Cache\\ChainAdapter::prune` method,
49+
the call is deligated to all its compatibe cache adapters. It is safe to mix both adapters
50+
that *do* and do *not* implement :class:`Symfony\\Component\\Cache\\PruneableInterface`, as
51+
incompatible adapters are silently ignored::
52+
53+
use Symfony\Component\Cache\Adapter\ApcuAdapter;
54+
use Symfony\Component\Cache\Adapter\ChainAdapter;
55+
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
56+
57+
$cache = new ChainAdapter(array(
58+
new ApcuAdapter(), // does NOT implement PruneableInterface
59+
new FilesystemAdapter(), // DOES implement PruneableInterface
60+
));
61+
62+
// prune will proxy the call to FilesystemAdapter while silently skipping ApcuAdapter
63+
$cache->prune();
64+
65+
.. note::
66+
67+
Since Symfony 3.4, this adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
68+
allowing for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
69+
calling its ``prune()`` method.

‎components/cache/adapters/filesystem_adapter.rst

Lines changed: 28 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,24 @@
22
single: Cache Pool
33
single: Filesystem Cache
44

5+
.. _component-cache-filesystem-adapter:
6+
57
Filesystem Cache Adapter
68
========================
79

8-
This adapter is useful when you want to improve the application performance but
9-
can't install tools like APCu or Redis on the server. This adapter stores the
10-
contents as regular files in a set of directories on the local file system.
10+
This adapter offers improved application performance for those who cannot install
11+
tools like :ref:`APCu <apcu-adapter>` or :ref:`Redis <redis-adapter>` in their
12+
environment. It stores the cache item expiration and content as regular files in
13+
a collection of directories on a locally mounted filesystem.
14+
15+
.. tip::
16+
17+
The performance of this adapter can be greatly increased by utalizing a
18+
temporary, in-memory filesystem, such as `tmpfs`_ on Linux, or one of the
19+
many other `RAM disk solutions`_ available.
1120

12-
This adapter can optionally be provided a namespace, default cache lifetime, and
13-
directory path, as its first, second, and third parameters::
21+
The FilesystemAdapter can optionally be provided a namespace, default cache lifetime,
22+
and cache root path as constructor parameters::
1423

1524
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
1625

@@ -30,9 +39,18 @@ directory path, as its first, second, and third parameters::
3039
$directory = null
3140
);
3241

33-
.. tip::
42+
.. caution::
43+
44+
The overhead of filesystem IO often makes this adapter one of the *slower* choices. If throughput is
45+
paramount, the in-memory adapters (:ref:`Apcu <apcu-adapter>`, :ref:`Memcached <memcached-adapter>`,
46+
and :ref:`Redis <redis-adapter>`) or the database adapters (:ref:`Doctrine <doctrine-adapter>` and
47+
:ref:`PDO <pdo-doctrine-adapter>`) are recommended.
48+
49+
.. note::
50+
51+
Since Symfony 3.4, this adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
52+
enabling manual :ref:`pruning of expired cache items <component-cache-cache-pool-prune>` by
53+
calling its ``prune()`` method.
3454

35-
This adapter is generally the *slowest* due to the overhead of file IO. If throughput is paramount,
36-
the in-memory adapters (such as :ref:`APCu <apcu-adapter>`, :ref:`Memcached <memcached-adapter>`,
37-
and :ref:`Redis <redis-adapter>`) or the database adapters (such as
38-
:ref:`Doctrine <doctrine-adapter>` and :ref:`PDO & Doctrine <pdo-doctrine-adapter>`) are recommended.
55+
.. _`tmpfs`: https://wiki.archlinux.org/index.php/tmpfs
56+
.. _`RAM disk solutions`: https://en.wikipedia.org/wiki/List_of_RAM_drive_software

‎components/cache/adapters/pdo_doctrine_dbal_adapter.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,12 @@ third, and forth parameters::
4040
When passed a `Data Source Name (DSN)`_ string (instead of a database connection
4141
class instance), the connection will be lazy-loaded when needed.
4242

43+
.. note::
44+
45+
Since Symfony 3.4, this adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
46+
allowing for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
47+
calling its ``prune()`` method.
48+
4349
.. _`PDO`: http://php.net/manual/en/class.pdo.php
4450
.. _`Doctrine DBAL Connection`: https://github.com/doctrine/dbal/blob/master/lib/Doctrine/DBAL/Connection.php
4551
.. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name

‎components/cache/adapters/php_array_cache_adapter.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ This adapter is a highly performant way to cache static data (e.g. application c
99
that is optimized and preloaded into OPcache memory storage::
1010

1111
use Symfony\Component\Cache\Adapter\PhpArrayAdapter;
12-
use Symfony\Component\Cache\Adapter\PhpFilesAdapter;
12+
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
1313

1414
// somehow, decide it's time to warm up the cache!
1515
if ($needsWarmup) {

‎components/cache/adapters/php_files_adapter.rst

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
.. index::
2+
single: Cache Pool
3+
single: PHP Files Cache
4+
5+
.. _component-cache-files-adapter:
6+
7+
Php Files Cache Adapter
8+
=======================
9+
10+
Similarly to :ref:`Filesystem Adapter <component-cache-filesystem-adapter>`, this cache
11+
implementation writes cache entries out to disk, but unlike the Filesystem cache adapter,
12+
the PHP Files cache adapter writes and reads back these cache files *as native PHP code*.
13+
For example, caching the value ``array('my', 'cached', 'array')`` will write out a cache
14+
file similar to the following::
15+
16+
<?php return array(
17+
18+
// the cache item expiration
19+
0 => 9223372036854775807,
20+
21+
// the cache item contents
22+
1 => array (
23+
0 => 'my',
24+
1 => 'cached',
25+
2 => 'array',
26+
),
27+
28+
);
29+
30+
.. note::
31+
32+
As cache items are included and parsed as native PHP code and due to the way `OPcache`_
33+
handles file includes, this adapter has the potential to be much faster than other
34+
filesystem-based caches.
35+
36+
The PhpFilesAdapter can optionally be provided a namespace, default cache lifetime, and cache
37+
directory path as constructor arguments::
38+
39+
use Symfony\Component\Cache\Adapter\PhpFilesAdapter;
40+
41+
$cache = new PhpFilesAdapter(
42+
43+
// a string used as the subdirectory of the root cache directory, where cache
44+
// items will be stored
45+
$namespace = '',
46+
47+
// the default lifetime (in seconds) for cache items that do not define their
48+
// own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
49+
// until the files are deleted)
50+
$defaultLifetime = 0,
51+
52+
// the main cache directory (the application needs read-write permissions on it)
53+
// if none is specified, a directory is created inside the system temporary directory
54+
$directory = null
55+
);
56+
57+
.. note::
58+
59+
Since Symfony 3.4, this adapter implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
60+
allowing for manual :ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
61+
calling its ``prune()`` method.
62+
63+
.. _`OPcache`: http://php.net/manual/en/book.opcache.php

‎components/cache/cache_invalidation.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,16 @@ your fronts and have very fast invalidation checks::
8080
new RedisAdapter('redis://localhost')
8181
);
8282

83+
.. note::
84+
85+
Since Symfony 3.4, :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter`
86+
implements :class:`Symfony\\Component\\Cache\\PruneableInterface`,
87+
enabling manual
88+
:ref:`pruning of expired cache entries <component-cache-cache-pool-prune>` by
89+
calling its :method:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter::prune`
90+
method (assuming the wrapped adapter itself implements
91+
:class:`Symfony\\Component\\Cache\\PruneableInterface`).
92+
8393
.. _cache-component-expiration:
8494

8595
Using Cache Expiration

‎components/cache/cache_pools.rst

Lines changed: 70 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ are independent from the actual cache implementation. Therefore, applications
2020
can keep using the same cache pool even if the underlying cache mechanism
2121
changes from a file system based cache to a Redis or database based cache.
2222

23+
.. _component-cache-creating-cache-pools:
24+
2325
Creating Cache Pools
2426
--------------------
2527

@@ -124,8 +126,9 @@ when all items are successfully deleted)::
124126

125127
.. tip::
126128

127-
If the Cache component is used inside a Symfony application, you can remove
128-
all the items of a given cache pool with the following command:
129+
If the cache component is used inside a Symfony application, you can remove
130+
*all items* from the *given pool(s)* using the following command (which resides within
131+
the :ref:`framework bundle <framework-bundle-configuration>`):
129132

130133
.. code-block:: terminal
131134
@@ -142,4 +145,68 @@ when all items are successfully deleted)::
142145
the cache pools, so you must use the ``cache:pool:clear`` command to
143146
delete them.
144147

145-
.. _`Doctrine Cache`: https://github.com/doctrine/cache
148+
.. _component-cache-cache-pool-prune:
149+
150+
Pruning Cache Items
151+
-------------------
152+
153+
.. versionadded:: 3.4
154+
155+
Cache adapter pruning functionality was introduced in Symfony 3.4.
156+
157+
Some cache pools do not include an automated mechanism for pruning expired cache items.
158+
For example, the :ref:`FilesystemAdaper <component-cache-filesystem-adapter>` cache
159+
does not remove expired cache items *until an item is explicitly requested and determined to
160+
be expired*, for example, via a call to :method:`Psr\\Cache\\CacheItemPoolInterface::getItem`.
161+
Under certain workloads, this can cause stale cache entries to persist well past their
162+
expiration, resulting in a sizable consumption of wasted disk or memory space from excess,
163+
expired cache items.
164+
165+
This shortcomming has been solved through the introduction of
166+
:class:`Symfony\\Component\\Cache\\PruneableInterface`, which defines the abstract method
167+
:method:`Symfony\\Component\\Cache\\PruneableInterface::prune`. The
168+
:ref:`ChainAdapter <component-cache-chain-adapter>`,
169+
:ref:`FilesystemAdaper <component-cache-filesystem-adapter>`,
170+
:ref:`PdoAdapter <pdo-doctrine-adapter>`, and
171+
:ref:`PhpFilesAdapter <component-cache-files-adapter>` all implement this new interface,
172+
allowing manual removal of stale cache items::
173+
174+
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
175+
176+
$cache = new FilesystemAdapter('app.cache');
177+
// ... do some set and get operations
178+
$cache->prune();
179+
180+
The :ref:`ChainAdapter <component-cache-chain-adapter>` implementation does not directly
181+
contain any pruning logic itself. Instead, when calling the chain adapter's
182+
:method:`Symfony\\Component\\Cache\\ChainAdapter::prune` method, the call is deligated to all
183+
its compatibe cache adapters (and those that do not implement ``PruneableInterface`` are
184+
silently ignored)::
185+
186+
use Symfony\Component\Cache\Adapter\ApcuAdapter;
187+
use Syfmony\Component\Cache\Adapter\ChainAdapter;
188+
use Syfmony\Component\Cache\Adapter\FilesystemAdapter;
189+
use Syfmony\Component\Cache\Adapter\PdoAdapter;
190+
use Syfmony\Component\Cache\Adapter\PhpFilesAdapter;
191+
192+
$cache = new ChainAdapter(array(
193+
new ApcuAdapter(), // does NOT implement PruneableInterface
194+
new FilesystemAdapter(), // DOES implement PruneableInterface
195+
new PdoAdapter(), // DOES implement PruneableInterface
196+
new PhpFilesAdapter(), // DOES implement PruneableInterface
197+
// ...
198+
));
199+
200+
// prune will proxy the call to PdoAdapter, FilesystemAdapter and PhpFilesAdapter,
201+
// while silently skipping ApcuAdapter
202+
$cache->prune();
203+
204+
.. tip::
205+
206+
If the cache component is used inside a Symfony application, you can prune
207+
*all items* from *all pools* using the following command (which resides within
208+
the :ref:`framework bundle <framework-bundle-configuration>`):
209+
210+
.. code-block:: terminal
211+
212+
$ php bin/console cache:pool:prune

‎reference/configuration/framework.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
.. index::
22
single: Configuration reference; Framework
33

4+
.. _framework-bundle-configuration:
5+
46
FrameworkBundle Configuration ("framework")
57
===========================================
68

0 commit comments

Comments
 (0)
0