Download the PHP package exteon/identity-cache without Composer
On this page you can find all versions of the php package exteon/identity-cache. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download exteon/identity-cache
More information about exteon/identity-cache
Files in exteon/identity-cache
Package identity-cache
Short Description Identity cache implementation
License Apache-2.0
Homepage https://github.com/exteon/identity-cache
Informations about the package identity-cache
IdentityCache
IdentityCache is a drop-in array replacement object cache designed to work with ORM and Identity Map patterns, providing Weakref-based unique identity-to-object resolution and smart caching of unused objects based on objects popularity
Abstract
The Identity Map pattern is very common in ORM implementations. It consists of an intermediate cache between the persistence and application layer, which is able to retrieve object instances by an unique object id. It must satisfy two requirements:
- For as long as an Identity is in use (the application layer holds any references to it), the Identity Map will retrieve the same instance when its id is queried. Otherwise, data consistency will be compromised when the application layer mutates different instances of the same identity.
- For Identities not in use, the Cache provides performance benefits by keeping instances for eventual reuse. It should however have a mechanism to discard cached instances so as not to consume excessive resources (i.e. memory).
Many implementations use a PHP native array to store an identity => instance map; however this has the disadvantage of storing instances indefinitely, ultimately filling up memory even though the references are not still in use.
Implementation
The IdentityCache implements Weakref-based caching to satisfy the requirements and a popularity-based garbage collection algorithm to keep the size of the cached unused instances into configurable limits.
The IdentityCache
and IdentityMap
are designed as drop-in replacements for a
native PHP array. The IdentityMap
does not provide caching functionality; as
soon as an object is not used anymore (its refcount drops to 0), the object is
freed.
Requirements
- For PHP > 7.4, use
Exteon\IdentityCache\Weakreference\IdentityMap
,Exteon\IdentityCache\Weakreference\IdentityMap
which use Weakreference - For PHP < 7.4, the Weakref extension
is needed. Then use
Exteon\IdentityCache\Weakref\IdentityMap
,Exteon\IdentityCache\Weakref\IdentityMap
- PHP < 7.2 not supported
Usage
Installing with composer
IdentityMap
IdentityCache
Configuration
An associative array can be passed to the constructor of
\Exteon\IdentityCache\WeakReference\IdentityCache
. Example usage, default and
possible values are shown below. If a configuration option is not passed to the
constructor, its default value will be used:
Popularity-based caching
When the purgeStrategy
config option is popularity
, a popularity index will
be kept for the cached objects. An object's popularity increases by 1 whenever
it is accessed from the cache.
In order to not keep forever objects that were once very popular but have not been used in a long time, an object's popularity also decays exponentially every time another object is accessed from the cache.
The value of the decay parameter can be specified by the popularityDecay
config option. This is a very sensitive float value that can be computed using
the getPopularityDecay()
method, as such:
The meaning of the parameters above, shown with default values, is:
If an object has at the present moment a popularity of initialPopularity
(1000), then other objects are accessed from the cache a number of rounds
(10000) times, the popularity of the initial object will drop to
targetPopularity
(2). By tweaking the value of popularityDecay
, you can
balance between keeping in the cache more of formerly popular objects or more of
recent objects.
Acquiring objects
Mapped objects can be explicitly 'acquired', meaning the map/cache will hold them indefinitely even if they are no longer in use (they won't be purged). This is needed for 'dirty' objects that have been mutated and will need to be persisted later in a write-behind strategy scenario.
Example:
Invoking the garbage collector explicitly
The garbage collector is normally invoked every time an identity is added to the
cache; it will then check if the trigger condition is satisfied and if so it
will proceed to purge excess objects from the cache. The gc can be also invoked
manually by calling the gc()
method on IdentityCache
.
Native PHP array replacements
If the Weakref
extension is not available, or for testing purposes, or for
an emergency in case the Weakref / WeakReference implementation is failing, we
provide regular array-based replacements for the Weakref IdentityMap
and
IdentityCache
:
\Exteon\IdentityCache\NativeArray\IdentityMap
\Exteon\IdentityCache\NativeArray\IdentityCache
These implement the same interfaces as their WeakRef / WeakReference
counterparts, so they can be dropped in their place, but they will not implement
any reference releasing functionality: objects added will remain in the
IdentityMap
or IdentityCache
until explicitly unset()
.