https://github.com/tysonandre/immutable_cache-pecl
Prototype PECL for faster immutable caching (fork of the APCu PECL)
https://github.com/tysonandre/immutable_cache-pecl
cache pecl php
Last synced: about 1 year ago
JSON representation
Prototype PECL for faster immutable caching (fork of the APCu PECL)
- Host: GitHub
- URL: https://github.com/tysonandre/immutable_cache-pecl
- Owner: TysonAndre
- License: other
- Created: 2022-10-23T02:29:01.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-09-16T16:24:51.000Z (almost 3 years ago)
- Last Synced: 2025-03-18T10:45:46.915Z (over 1 year ago)
- Topics: cache, pecl, php
- Language: C
- Homepage:
- Size: 1.72 MB
- Stars: 23
- Watchers: 3
- Forks: 2
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
immutable\_cache
================
[](https://github.com/TysonAndre/immutable_cache-pecl/actions/workflows/config.yml?query=branch%3Amain)
[](https://ci.appveyor.com/project/TysonAndre/immutable-cache-pecl/branch/main)
The [`immutable_cache` PECL](https://pecl.php.net/package/immutable_cache) adds functionality similar to APCu,
but with immutable values (either the values themselves or an immutable serialized copy of mutable values is stored in the shared memory region)
See [the installing section](#installing) for installation instructions.
This is a fork of the original [APCu PECL](https://github.com/krakjoe/apcu)
Features:
- Returns the original persistent strings/arrays rather than a copy (for arrays that don't contain objects or PHP references)
(not possible in a **mutable** in-memory pool with [APCu](https://github.com/krakjoe/apcu) due to eviction always being possible in APCu)
This is instantaneous regardless of how large the array or strings are.
- Reuses immutable values if they were fetched from immutable_cache and stored again.
Planned but unimplemented features:
- Aggressively deduplicate values across cache entries (not possible in APCu due to the need to cache entries separately)
Benefits:
- You can be certain that a value added to the cache doesn't get removed.
- You can efficiently fetch entire immutable arrays or strings without copying or using extra memory
in cases where the serializer is not required.
(APCu needs to make copies of all strings and arrays in case of a cache clear during a request)
Caveats:
- APCu will also clear the shared memory cache as a way to recover from deadlocks or processes crashing while holding the shared memory lock, which should be rare (e.g. a process getting killed or crashing while copying values).
immutable_cache will never clear the shared memory cache.
Features
========
`immutable_cache` is an in-memory key-value store for PHP. Keys are of type string and values can be any PHP variables.
### API reference
This provides an API similar to a subset of the functions in https://php.net/apcu , but does not allow for modifying, deleting, incrementing, etc. on a created key.
When storing mutable values such as objects, it will instead call PHP's serialize() on the entire object.
Each retrieval will call unserialize() and return different values when the underlying value is mutable.
```php
string array of size 8 with 4 forked processes
Note that the immutable array and strings part of shared memory in immutable_cache, where apcu must make copies of strings and arrays to account for eviction (and php must free them)
{"key0":"myValue0","key1":"myValue1","key2":"myValue2","key3":"myValue3","key4":"myValue4","key5":"myValue5","key6":"myValue6","key7":"myValue7"}
immutable_cache Elapsed: 0.053691 throughput 7450103 / second
immutable_cache Elapsed: 0.056164 throughput 7121941 / second
immutable_cache Elapsed: 0.054956 throughput 7278549 / second
immutable_cache Elapsed: 0.059204 throughput 6756267 / second
APCu Elapsed: 0.318515 throughput 1255828 / second
APCu Elapsed: 0.314734 throughput 1270913 / second
APCu Elapsed: 0.320162 throughput 1249368 / second
APCu Elapsed: 0.327550 throughput 1221189 / second
```
Installing
==========
## Compile immutable_cache in Linux
```
$ phpize
$ ./configure
$ make
$ make test
$ make install
```
Add the following line to your php.ini
```
extension=immutable_cache.so
```
## Compile immutable_cache in Windows
See https://wiki.php.net/internals/windows/stepbystepbuild_sdk_2#building_pecl_extensions and .appveyor.yml for how to build this.
Reporting Bugs
=============
If you believe you have found a bug in `immutable_cache`, please open an issue: Include in your report *minimal, executable, reproducing code*.
Minimal: reduce your problem to the smallest amount of code possible; This helps with hunting the bug, but also it helps with integration and regression testing once the bug is fixed.
Executable: include all the information required to execute the example code, code snippets are not helpful.
Reproducing: some bugs don't show themselves on every execution, that's fine, mention that in the report and give an idea of how often you encounter the bug.
__It is impossible to help without reproducing code, bugs that are opened without reproducing code will be closed.__
Please include version and operating system information in your report.