<h1><a href="https://github.com/McCache/McCache-for-Python/blob/main/README.md">
<!--
<img src="https://github.com/McCache/McCache-for-Python/blob/main/docs/McCache%20Logo.png?raw=true" width="200" height="200" alt="McCache for Python">
-->
<img src="https://github.com/McCache/McCache-for-Python/blob/main/docs/McCache%20Logo%20-%20Rectangle.png?raw=true" width="200" height="150" alt="McCache for Python">
</a>
</h1>
<!-- Not working in GitHub
<style scoped>
table {
font-size: 12px;
}
</style>
-->
## Overview
`McCache` is a, write through cluster aware, local in-memory caching library that is build on Python's [`OrderedDict`](https://docs.python.org/3/library/collections.html#collections.OrderedDict) package. A local cache lookup is faster than retrieving it across a network.
It uses **UDP** multicast as the transport hence the name "Multi-Cast Cache", playfully abbreviated to "`McCache`".
The goals of this package are:
1. Reduce complexity by **not** be dependent on any external caching service such as `memcached`, `redis` or the likes. SEE: [Distributed Cache](https://en.wikipedia.org/wiki/Distributed_cache)
* We are guided by the principal of first scaling up before scaling out.
2. Keep the same Python programming experience. It is the same Python's dictionary interface. The distributed nature of the cache is transparent to you.
* This is an in-process cache that is cluster aware.
3. Performant
* Need to handle rapid updates that are 0.01sec (10 ms) or faster.
4. Secure
* All transmissions across the network are encrypted.
`McCache` is **not** a replacement for your persistent or search data. It is intended to be used to cache your most expensive work. You can consider the Pareto Principle [**80/20**](https://en.wikipedia.org/wiki/Pareto_principle) rule, which states that caching **20%** of the most frequently accessed **80%** data can improve performance for most requests. This principle offers you the option to reduce your hardware requirement. Only you can decide how much to cache.
## Installation
```console
pip install mccache
```
## Example
```python
import mccache
from datetime import UTC
from datetime import datetime as dt
from pprint import pprint as pp
c = mccache.get_cache( 'demo' )
k = 'k1'
c[ k ] = dt.now( UTC ) # Insert a cache entry
print(f"Inserted on {c[ k ]}")
c[ k ] = dt.now( UTC ) # Update a cache entry
print(f"Updated on {c[ k ]}")
print(f"Metadata for key '{k}' is {c.metadata[ k ]}")
del c[ k ] # Delete a cache entry
if k not in c:
print(f" {k} is not in the cache.")
k = 'k2'
c[ k ] = dt.now( UTC ) # Insert another cache entry
print(f"Inserted on {c[ k ]}")
# At this point all the cache with namespace 'demo' in the cluster are identical with just one entry with key 'k2'.
# Query the local cache checksum and metrics.
pp( mccache.get_local_checksum( 'demo' ))
pp( mccache.get_local_metrics( 'demo' ))
# Request the other members in the cluster to log out their local cache metrics.
mccache.get_cluster_metrics()
```
In the above example, there is **nothing** different in the usage of `McCache` from a regular Python dictionary. However, the benefit is in a clustered environment where the other subscribed member's cache are kept coherent with the changes to your local cache.
## Guidelines
The following are some loose guidelines to help you assess if the `McCache` library is right for your project.
* You have a need to **not** depend on external caching service.
* You want to keep the programming **consistency** of a Python dictionary.
* You have a **small** cluster of identically configured nodes.
* You have a **medium** size set of objects to cache.
* Your cached objects do not mutate **frequently**.
* Your cached objects size is **small**.
* Your cluster environment is secured by **other** means.
* Your nodes clock in the cluster are **well** synchronized.
The adjectives used above have been intended to be loose and should be quantified to your environment and needs.<br>
**SEE**: [Testing](https://github.com/McCache/McCache-for-Python/blob/main/docs/TESTING.md)
You can review the script used in the stress test.<br>
**SEE**: [Test script](https://github.com/McCache/McCache-for-Python/blob/main/tests/unit/start_mccache.py)
You should clone this repo down and run the test in a local `docker`/`podman` cluster.<br>
**SEE**: [Contributing](https://github.com/McCache/McCache-for-Python/blob/main/docs/CONTRIBUTING.md#Tests)
We suggest the following testing to collect metrics of your application running in your environment.
1. Import the `McCache` library into your project.
2. Use it in your data access layer by populating and updating the cache but **don't** use the cached values.
3. Configure to enable the debug logging by providing a path for your log file.
4. Compare the retrieved values between your existing cache and from `McCache`.
5. Run your application for an extended period and exit.
6. Log the summary metric out for more extended analysis.
7. Review the metrics to quantify the fit to your application and environment. **SEE**: [Testing](https://github.com/McCache/McCache-for-Python/blob/main/docs/TESTING.md#container)
## Saving
Removing an external dependency in your architecture reduces it's <strong>complexity</strong> and not to mention some capital cost saving.<br>
**SEE**: [Cloud Savings](https://github.com/McCache/McCache-for-Python/blob/main/docs/SAVING.md)
## Configuration
The following are environment variables you can tune to fit your production environment needs.
<table>
<thead>
<tr>
<th align="left">Name</th>
<th align="left">Default</th>
<th align="left">Comment</th>
</tr>
</thead>
<tbody>
<tr>
<td><sub>MCCACHE_CACHE_TTL</sub></td>
<td>3600 secs (1 hour)</td>
<td>Maximum number of seconds a cached entry can live before eviction. Update operations shall reset the timer.</td>
</tr>
<tr>
<td><sub>MCCACHE_CACHE_MAX</sub></td>
<td>256 entries</td>
<td>The maximum entries per cache.</td>
</tr>
<tr>
<td><sub>MCCACHE_CACHE_MODE</sub></td>
<td>1</td>
<td>The degree of keeping the cache coherent in the cluster.<br>
<b>0</b>: Only members that has the same key in their cache shall be updated.<br>
<b>1</b>: All members cache shall be kept fully coherent and synchronized.<br></td>
</tr>
<tr>
<td><sub>MCCACHE_CACHE_SIZE</sub></td>
<td>8,388,608 bytes (8Mb)</td>
<td>The maximum in-memory size per cache.</td>
</tr>
<tr>
<td><sub>MCCACHE_CACHE_PULSE</sub></td>
<td>300 secs (5 min)</td>
<td>The interval to send out a synchronization pulse operation to the other members in the cluster.</td>
</tr>
<tr>
<td><sub>MCCACHE_CRYPTO_KEY</sub></td>
<td></td>
<td>The encryption/decryption key. Cryptography shall be enabled if presence of a key value. Generate the key as follows:
<code><br>
from cryptography.fernet import Fernet<br>
print( Fernet.generate_key() )
</code><br>Enabling this will increase the payload size by at least 30% and also increase CPU processing.
</td>
</tr>
<tr>
<td><sub>MCCACHE_PACKET_MTU</sub></td>
<td>1472 bytes</td>
<td>The size of the smallest transfer unit of the network packet between all the network interfaces.<br>Generally, ethernet frame is <b>1500</b> without the static <b>20</b> bytes IP and <b>8</b> bytes ICMP headers.<br><b>SEE</b>: <code>mccache.get_mtu()</code></td>
</tr>
<tr>
<td><sub>MCCACHE_MULTICAST_IP</sub></td>
<td>224.0.0.3 [ :4000 ]</td>
<td>The multicast IP address and the optional port number for your group to multicast within.
<br><b>SEE</b>: <a href="https://www.iana.org/assignments/multicast-addresses/multicast-addresses.xhtml">IANA multicast addresses</a>.</td>
</tr>
<tr>
<td><sub>MCCACHE_MULTICAST_HOPS</sub></td>
<td>3 hops</td>
<td>The maximum network hops. 1 is just within the same switch/router. [>=1]<br><b>SEE</b>: <code>mccache.get_hops()</code></td>
</tr>
<tr>
<td><sub>MCCACHE_CALLBACK_WIN</sub></td>
<td>5 secs</td>
<td>The window, in seconds, where the last lookup and the current change falls in to trigger a callback to a function provided by you. </td>
</tr>
<tr>
<td><sub>MCCACHE_DAEMON_SLEEP</sub></td>
<td>1 sec</td>
<td>The snooze duration for the daemon housekeeper before waking up to check the state of the cache.</td>
</tr>
<tr>
<td><sub>MCCACHE_LOG_FILENAME</sub></td>
<td>./log/mccache.log</td>
<td>The local filename where output log messages are appended to.</td>
</tr>
<tr>
<td><sub>MCCACHE_LOG_FORMAT</sub></td>
<td></td>
<td>The custom logging format for your project.
<br><b>SEE</b>: Variables <code>log_format</code> and <code>log_msgfmt</code> in <code>__init__.py</code></td>
</tr>
<tr>
<td colspan=3><b>The following are parameters you can tune to fit your stress testing needs.</b></td>
<tr>
<tr>
<td><sub>TEST_RANDOM_SEED</sub></td>
<td>4th octet of the IP address</td>
<td>The random seed for each different node in the test cluster.</td>
</tr>
<tr>
<td><sub>TEST_KEY_ENTRIES</sub></td>
<td>200 key/values</td>
<td>The maximum of randomly generated keys.<br>
The smaller the number, the higher the chance of cache collision.
Tune this number down to add stress to the test.</td>
</tr>
<tr>
<td><sub>TEST_DATA_SIZE_MIX</sub></td>
<td>1</td>
<td>The data packet size mix.<br>
<b>1</b>: Cache small objects where size < 1Kb.<br>
<b>2</b>: Cache large objects where size > 9Kb.<br>
<b>3</b>: Random mix of small and large objects.<br>
Tune this number to 2 to add stress to the test.</td>
</tr>
<tr>
<td><sub>TEST_RUN_DURATION</sub></td>
<td>5 mins</td>
<td>The duration in minutes of the testing run. <br>
The larger the number, the longer the test run/duration.
Tune this number up to add stress to the test.</td>
</tr>
<tr>
<td><sub>TEST_APERTURE</sub></td>
<td>0.01 sec</td>
<td>The centerpoint of a range of durations to snooze within.
e.g. For the value of 0.01, 10ms, the snooze range shall be between 6.5ms and 13.5ms.
Tune this number down to add stress to the test.</td>
</tr>
<tr>
<td><sub>TEST_MONKEY_TANTRUM</sub></td>
<td>0</td>
<td>The percentage of drop packets. <br>
The larger the number, the more unsent packets.
Tune this number up to add stress to the test.</td>
</tr>
</tbody>
</table>
### pyproject.toml
Specifying tuning parameters via `pyproject.toml` file.
```toml
[tool.mccache]
cache_ttl = 900
packet_mtu = 1472
```
### Environment variables
Specifying tuning parameters via environment variables.
```bash
# Unix
export MCCACHE_TTL=900
export MCCACHE_MTU=1472
```
```bat
:: Windows
SET MCCACHE_TTL=900
SET MCCACHE_MTU=1472
```
Environment variables supersede the setting in the `pyproject.toml` file.
## Environment check
Two utility methods are provided to assist you to determined the size of the MTU in your network and the number of network hops to the other members in the cluster. The following is an example to invoke these methods:
```python
import mccache
# Get the maximum MTU between here to another cluster member.
mccache.get_mtu( '142.251.32.36' )
# Get the number of network hops between here to another cluster member.
mccache.get_hops( '142.251.32.36' ,20 )
```
## Public utility methods
```python
# Factory method to get a cache instance.
def get_cache( name: str | None=None ,callback: FunctionType = _default_callback ) -> PyCache:
# Clear all the distributed caches.
def clear_cache( name: str | None = None ,node: str | None = None ) -> None:
# Get the maximum MTU between this and the another cluster member.
def get_mtu( ip_add: str ) -> None:
# Get the number of network hops between this and another cluster member.
def get_hops( ip_add: str ,max_hops: int | None = 20 ) -> None:
# Get the instance cache metrics from the current node.
def get_local_metrics( name: str | None = None ) -> dict:
# Get the instance cache checksum from the current node.
def get_local_checksum( name: str | None = None ,key: str | None = None ) -> dict:
# Request all members to output their metrics into their log.
def get_cluster_metrics( name: str | None = None ,node: str | None = None ) -> None:
# Request all members to output their cache checksum into their log..
def get_cluster_checksum( name: str | None = None ,key: str | None = None ,node: str | None = None ) -> None:
```
## Design
* SEE: [Design gist](https://github.com/McCache/McCache-for-Python/blob/main/docs/DESIGN.md).
## Background Story
* SEE: [Background story](https://github.com/McCache/McCache-for-Python/blob/main/docs/BACKGROUND.md).
## Releases
Releases are recorded [here](https://github.com/McCache/McCache-for-Python/issues).
## License
`McCache` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
## Contribute
We welcome your contribution. Please read [contributing](https://github.com/McCache/McCache-for-Python/blob/main/docs/CONTRIBUTING.md) to learn how to get setup to contribute to this project.
`McCache` is still a young project. With that said, please try it out in your applications: We need your feedback to fix the bugs and file down the rough edges.
Issues and feature request can be posted [here](https://github.com/McCache/McCache-for-Python/issues). Help us port this library to other languages. The repos are setup under the [GitHub `McCache` organization](https://github.com/mccache).
You can reach our administrator at `elau1004@netscape.net`.
## Support
For any inquiries, bug reports, or feature requests, please open an issue in the [GitHub repository](https://github.com/McCache/McCache-for-Python/issues).
## Miscellaneous
* SEE: [Latency Numbers](https://gist.github.com/hellerbarde/2843375)
* SEE: [Determine the size of the MTU in your network.](https://www.youtube.com/watch?v=Od5SEHEZnVU)
* SEE: [Network maximum transmission unit (MTU) for your EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/network_mtu.html)
* SEE: [Setting MTU size for jumbo frames on OCI instance interfaces](https://support.checkpoint.com/results/sk/sk167534)
Different cloud provider uses different size.
* SEE: [Enabling Sticky Sessions](https://www.youtube.com/watch?v=hTp4czOrvOY")
* SEE: [In-Process vs Distributed](https://dzone.com/articles/process-caching-vs-distributed)
Raw data
{
"_id": null,
"home_page": null,
"name": "McCache",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Edward Lau <elau1004@netscape.net>",
"keywords": "cache, cluster, distributed, eventual, local, mccache, multicast, optimistic, performance, scale-out, scale-up, udp",
"author": null,
"author_email": "Edward Lau <elau1004@netscape.net>",
"download_url": null,
"platform": null,
"description": "<h1><a href=\"https://github.com/McCache/McCache-for-Python/blob/main/README.md\">\n<!--\n<img src=\"https://github.com/McCache/McCache-for-Python/blob/main/docs/McCache%20Logo.png?raw=true\" width=\"200\" height=\"200\" alt=\"McCache for Python\">\n-->\n<img src=\"https://github.com/McCache/McCache-for-Python/blob/main/docs/McCache%20Logo%20-%20Rectangle.png?raw=true\" width=\"200\" height=\"150\" alt=\"McCache for Python\">\n</a>\n</h1>\n\n<!-- Not working in GitHub\n<style scoped>\ntable {\n font-size: 12px;\n}\n</style>\n-->\n\n## Overview\n`McCache` is a, write through cluster aware, local in-memory caching library that is build on Python's [`OrderedDict`](https://docs.python.org/3/library/collections.html#collections.OrderedDict) package. A local cache lookup is faster than retrieving it across a network.\nIt uses **UDP** multicast as the transport hence the name \"Multi-Cast Cache\", playfully abbreviated to \"`McCache`\".\n\nThe goals of this package are:\n1. Reduce complexity by **not** be dependent on any external caching service such as `memcached`, `redis` or the likes. SEE: [Distributed Cache](https://en.wikipedia.org/wiki/Distributed_cache)\n * We are guided by the principal of first scaling up before scaling out.\n2. Keep the same Python programming experience. It is the same Python's dictionary interface. The distributed nature of the cache is transparent to you.\n * This is an in-process cache that is cluster aware.\n3. Performant\n * Need to handle rapid updates that are 0.01sec (10 ms) or faster.\n4. Secure\n * All transmissions across the network are encrypted.\n\n`McCache` is **not** a replacement for your persistent or search data. It is intended to be used to cache your most expensive work. You can consider the Pareto Principle [**80/20**](https://en.wikipedia.org/wiki/Pareto_principle) rule, which states that caching **20%** of the most frequently accessed **80%** data can improve performance for most requests. This principle offers you the option to reduce your hardware requirement. Only you can decide how much to cache.\n\n## Installation\n```console\npip install mccache\n```\n\n## Example\n```python\nimport mccache\nfrom datetime import UTC\nfrom datetime import datetime as dt\nfrom pprint import pprint as pp\n\nc = mccache.get_cache( 'demo' )\nk = 'k1'\n\nc[ k ] = dt.now( UTC ) # Insert a cache entry\nprint(f\"Inserted on {c[ k ]}\")\n\nc[ k ] = dt.now( UTC ) # Update a cache entry\nprint(f\"Updated on {c[ k ]}\")\nprint(f\"Metadata for key '{k}' is {c.metadata[ k ]}\")\n\ndel c[ k ] # Delete a cache entry\nif k not in c:\n print(f\" {k} is not in the cache.\")\n\nk = 'k2'\nc[ k ] = dt.now( UTC ) # Insert another cache entry\nprint(f\"Inserted on {c[ k ]}\")\n\n# At this point all the cache with namespace 'demo' in the cluster are identical with just one entry with key 'k2'.\n\n# Query the local cache checksum and metrics.\npp( mccache.get_local_checksum( 'demo' ))\npp( mccache.get_local_metrics( 'demo' ))\n\n# Request the other members in the cluster to log out their local cache metrics.\nmccache.get_cluster_metrics()\n```\n\nIn the above example, there is **nothing** different in the usage of `McCache` from a regular Python dictionary. However, the benefit is in a clustered environment where the other subscribed member's cache are kept coherent with the changes to your local cache.\n\n## Guidelines\nThe following are some loose guidelines to help you assess if the `McCache` library is right for your project.\n\n* You have a need to **not** depend on external caching service.\n* You want to keep the programming **consistency** of a Python dictionary.\n* You have a **small** cluster of identically configured nodes.\n* You have a **medium** size set of objects to cache.\n* Your cached objects do not mutate **frequently**.\n* Your cached objects size is **small**.\n* Your cluster environment is secured by **other** means.\n* Your nodes clock in the cluster are **well** synchronized.\n\nThe adjectives used above have been intended to be loose and should be quantified to your environment and needs.<br>\n**SEE**: [Testing](https://github.com/McCache/McCache-for-Python/blob/main/docs/TESTING.md)\n\nYou can review the script used in the stress test.<br>\n**SEE**: [Test script](https://github.com/McCache/McCache-for-Python/blob/main/tests/unit/start_mccache.py)\n\nYou should clone this repo down and run the test in a local `docker`/`podman` cluster.<br>\n**SEE**: [Contributing](https://github.com/McCache/McCache-for-Python/blob/main/docs/CONTRIBUTING.md#Tests)\n\nWe suggest the following testing to collect metrics of your application running in your environment.\n1. Import the `McCache` library into your project.\n2. Use it in your data access layer by populating and updating the cache but **don't** use the cached values.\n3. Configure to enable the debug logging by providing a path for your log file.\n4. Compare the retrieved values between your existing cache and from `McCache`.\n5. Run your application for an extended period and exit.\n6. Log the summary metric out for more extended analysis.\n7. Review the metrics to quantify the fit to your application and environment. **SEE**: [Testing](https://github.com/McCache/McCache-for-Python/blob/main/docs/TESTING.md#container)\n\n## Saving\nRemoving an external dependency in your architecture reduces it's <strong>complexity</strong> and not to mention some capital cost saving.<br>\n**SEE**: [Cloud Savings](https://github.com/McCache/McCache-for-Python/blob/main/docs/SAVING.md)\n\n## Configuration\nThe following are environment variables you can tune to fit your production environment needs.\n<table>\n<thead>\n <tr>\n <th align=\"left\">Name</th>\n <th align=\"left\">Default</th>\n <th align=\"left\">Comment</th>\n </tr>\n</thead>\n<tbody>\n <tr>\n <td><sub>MCCACHE_CACHE_TTL</sub></td>\n <td>3600 secs (1 hour)</td>\n <td>Maximum number of seconds a cached entry can live before eviction. Update operations shall reset the timer.</td>\n </tr>\n <tr>\n <td><sub>MCCACHE_CACHE_MAX</sub></td>\n <td>256 entries</td>\n <td>The maximum entries per cache.</td>\n </tr>\n <tr>\n <td><sub>MCCACHE_CACHE_MODE</sub></td>\n <td>1</td>\n <td>The degree of keeping the cache coherent in the cluster.<br>\n <b>0</b>: Only members that has the same key in their cache shall be updated.<br>\n <b>1</b>: All members cache shall be kept fully coherent and synchronized.<br></td>\n </tr>\n <tr>\n <td><sub>MCCACHE_CACHE_SIZE</sub></td>\n <td>8,388,608 bytes (8Mb)</td>\n <td>The maximum in-memory size per cache.</td>\n </tr>\n <tr>\n <td><sub>MCCACHE_CACHE_PULSE</sub></td>\n <td>300 secs (5 min)</td>\n <td>The interval to send out a synchronization pulse operation to the other members in the cluster.</td>\n </tr>\n <tr>\n <td><sub>MCCACHE_CRYPTO_KEY</sub></td>\n <td></td>\n <td>The encryption/decryption key. Cryptography shall be enabled if presence of a key value. Generate the key as follows:\n <code><br>\n from cryptography.fernet import Fernet<br>\n print( Fernet.generate_key() )\n </code><br>Enabling this will increase the payload size by at least 30% and also increase CPU processing. \n </td>\n </tr>\n <tr>\n <td><sub>MCCACHE_PACKET_MTU</sub></td>\n <td>1472 bytes</td>\n <td>The size of the smallest transfer unit of the network packet between all the network interfaces.<br>Generally, ethernet frame is <b>1500</b> without the static <b>20</b> bytes IP and <b>8</b> bytes ICMP headers.<br><b>SEE</b>: <code>mccache.get_mtu()</code></td>\n </tr>\n <tr>\n <td><sub>MCCACHE_MULTICAST_IP</sub></td>\n <td>224.0.0.3 [ :4000 ]</td>\n <td>The multicast IP address and the optional port number for your group to multicast within.\n <br><b>SEE</b>: <a href=\"https://www.iana.org/assignments/multicast-addresses/multicast-addresses.xhtml\">IANA multicast addresses</a>.</td>\n </tr>\n <tr>\n <td><sub>MCCACHE_MULTICAST_HOPS</sub></td>\n <td>3 hops</td>\n <td>The maximum network hops. 1 is just within the same switch/router. [>=1]<br><b>SEE</b>: <code>mccache.get_hops()</code></td>\n </tr>\n <tr>\n <td><sub>MCCACHE_CALLBACK_WIN</sub></td>\n <td>5 secs</td>\n <td>The window, in seconds, where the last lookup and the current change falls in to trigger a callback to a function provided by you. </td>\n </tr>\n <tr>\n <td><sub>MCCACHE_DAEMON_SLEEP</sub></td>\n <td>1 sec</td>\n <td>The snooze duration for the daemon housekeeper before waking up to check the state of the cache.</td>\n </tr>\n <tr>\n <td><sub>MCCACHE_LOG_FILENAME</sub></td>\n <td>./log/mccache.log</td>\n <td>The local filename where output log messages are appended to.</td>\n </tr>\n <tr>\n <td><sub>MCCACHE_LOG_FORMAT</sub></td>\n <td></td>\n <td>The custom logging format for your project.\n <br><b>SEE</b>: Variables <code>log_format</code> and <code>log_msgfmt</code> in <code>__init__.py</code></td>\n </tr>\n <tr>\n <td colspan=3><b>The following are parameters you can tune to fit your stress testing needs.</b></td>\n <tr>\n <tr>\n <td><sub>TEST_RANDOM_SEED</sub></td>\n <td>4th octet of the IP address</td>\n <td>The random seed for each different node in the test cluster.</td>\n </tr>\n <tr>\n <td><sub>TEST_KEY_ENTRIES</sub></td>\n <td>200 key/values</td>\n <td>The maximum of randomly generated keys.<br>\n The smaller the number, the higher the chance of cache collision.\n Tune this number down to add stress to the test.</td>\n </tr>\n <tr>\n <td><sub>TEST_DATA_SIZE_MIX</sub></td>\n <td>1</td>\n <td>The data packet size mix.<br>\n <b>1</b>: Cache small objects where size < 1Kb.<br>\n <b>2</b>: Cache large objects where size > 9Kb.<br>\n <b>3</b>: Random mix of small and large objects.<br>\n Tune this number to 2 to add stress to the test.</td>\n </tr>\n <tr>\n <td><sub>TEST_RUN_DURATION</sub></td>\n <td>5 mins</td>\n <td>The duration in minutes of the testing run. <br>\n The larger the number, the longer the test run/duration.\n Tune this number up to add stress to the test.</td>\n </tr>\n <tr>\n <td><sub>TEST_APERTURE</sub></td>\n <td>0.01 sec</td>\n <td>The centerpoint of a range of durations to snooze within.\n e.g. For the value of 0.01, 10ms, the snooze range shall be between 6.5ms and 13.5ms.\n Tune this number down to add stress to the test.</td>\n </tr>\n <tr>\n <td><sub>TEST_MONKEY_TANTRUM</sub></td>\n <td>0</td>\n <td>The percentage of drop packets. <br>\n The larger the number, the more unsent packets.\n Tune this number up to add stress to the test.</td>\n </tr>\n</tbody>\n</table>\n\n### pyproject.toml\nSpecifying tuning parameters via `pyproject.toml` file.\n```toml\n[tool.mccache]\ncache_ttl = 900\npacket_mtu = 1472\n```\n### Environment variables\nSpecifying tuning parameters via environment variables.\n```bash\n# Unix\nexport MCCACHE_TTL=900\nexport MCCACHE_MTU=1472\n```\n```bat\n:: Windows\nSET MCCACHE_TTL=900\nSET MCCACHE_MTU=1472\n```\nEnvironment variables supersede the setting in the `pyproject.toml` file.\n\n## Environment check\nTwo utility methods are provided to assist you to determined the size of the MTU in your network and the number of network hops to the other members in the cluster. The following is an example to invoke these methods:\n```python\nimport mccache\n\n# Get the maximum MTU between here to another cluster member.\nmccache.get_mtu( '142.251.32.36' )\n\n# Get the number of network hops between here to another cluster member.\nmccache.get_hops( '142.251.32.36' ,20 )\n```\n\n## Public utility methods\n```python\n# Factory method to get a cache instance.\ndef get_cache( name: str | None=None ,callback: FunctionType = _default_callback ) -> PyCache:\n\n# Clear all the distributed caches.\ndef clear_cache( name: str | None = None ,node: str | None = None ) -> None:\n\n# Get the maximum MTU between this and the another cluster member.\ndef get_mtu( ip_add: str ) -> None:\n\n# Get the number of network hops between this and another cluster member.\ndef get_hops( ip_add: str ,max_hops: int | None = 20 ) -> None:\n\n# Get the instance cache metrics from the current node.\ndef get_local_metrics( name: str | None = None ) -> dict:\n\n# Get the instance cache checksum from the current node.\ndef get_local_checksum( name: str | None = None ,key: str | None = None ) -> dict:\n\n# Request all members to output their metrics into their log.\ndef get_cluster_metrics( name: str | None = None ,node: str | None = None ) -> None:\n\n# Request all members to output their cache checksum into their log..\ndef get_cluster_checksum( name: str | None = None ,key: str | None = None ,node: str | None = None ) -> None:\n```\n\n## Design\n* SEE: [Design gist](https://github.com/McCache/McCache-for-Python/blob/main/docs/DESIGN.md).\n\n## Background Story\n* SEE: [Background story](https://github.com/McCache/McCache-for-Python/blob/main/docs/BACKGROUND.md).\n\n## Releases\nReleases are recorded [here](https://github.com/McCache/McCache-for-Python/issues).\n\n## License\n`McCache` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n\n## Contribute\nWe welcome your contribution. Please read [contributing](https://github.com/McCache/McCache-for-Python/blob/main/docs/CONTRIBUTING.md) to learn how to get setup to contribute to this project.\n\n`McCache` is still a young project. With that said, please try it out in your applications: We need your feedback to fix the bugs and file down the rough edges.\n\nIssues and feature request can be posted [here](https://github.com/McCache/McCache-for-Python/issues). Help us port this library to other languages. The repos are setup under the [GitHub `McCache` organization](https://github.com/mccache).\nYou can reach our administrator at `elau1004@netscape.net`.\n\n## Support\nFor any inquiries, bug reports, or feature requests, please open an issue in the [GitHub repository](https://github.com/McCache/McCache-for-Python/issues).\n\n## Miscellaneous\n* SEE: [Latency Numbers](https://gist.github.com/hellerbarde/2843375)\n* SEE: [Determine the size of the MTU in your network.](https://www.youtube.com/watch?v=Od5SEHEZnVU)\n* SEE: [Network maximum transmission unit (MTU) for your EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/network_mtu.html)\n* SEE: [Setting MTU size for jumbo frames on OCI instance interfaces](https://support.checkpoint.com/results/sk/sk167534)\nDifferent cloud provider uses different size.\n* SEE: [Enabling Sticky Sessions](https://www.youtube.com/watch?v=hTp4czOrvOY\")\n* SEE: [In-Process vs Distributed](https://dzone.com/articles/process-caching-vs-distributed)\n",
"bugtrack_url": null,
"license": null,
"summary": "McCache is a, write through cluster aware, local in-memory caching library.",
"version": "0.4.10",
"project_urls": {
"Homepage": "https://github.com/McCache/McCache-for-Python",
"Issues": "https://github.com/McCache/McCache-for-Python/issues",
"Source": "https://github.com/McCache/McCache-for-Python"
},
"split_keywords": [
"cache",
" cluster",
" distributed",
" eventual",
" local",
" mccache",
" multicast",
" optimistic",
" performance",
" scale-out",
" scale-up",
" udp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c0e527d1233aeb8f1dff10feff12b367ea63a2e3de469289d5cb02892805ce8a",
"md5": "71d2f92dc159377558b6104ad52c15d2",
"sha256": "cfbb6effb2f0c47bb39f78f2689faa200c0bb9d0d09c84f914fc5c2b3c15c9d9"
},
"downloads": -1,
"filename": "mccache-0.4.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "71d2f92dc159377558b6104ad52c15d2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 51129,
"upload_time": "2025-02-23T01:05:08",
"upload_time_iso_8601": "2025-02-23T01:05:08.469212Z",
"url": "https://files.pythonhosted.org/packages/c0/e5/27d1233aeb8f1dff10feff12b367ea63a2e3de469289d5cb02892805ce8a/mccache-0.4.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-23 01:05:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "McCache",
"github_project": "McCache-for-Python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "psutil",
"specs": [
[
">=",
"5.9.5"
]
]
},
{
"name": "faker",
"specs": [
[
">=",
"25.0.1"
]
]
},
{
"name": "cryptography",
"specs": [
[
">=",
"44.0.0"
]
]
}
],
"lcname": "mccache"
}
JSON
