1dogpile 2======= 3 4Dogpile consists of two subsystems, one building on top of the other. 5 6``dogpile`` provides the concept of a "dogpile lock", a control structure 7which allows a single thread of execution to be selected as the "creator" of 8some resource, while allowing other threads of execution to refer to the previous 9version of this resource as the creation proceeds; if there is no previous 10version, then those threads block until the object is available. 11 12``dogpile.cache`` is a caching API which provides a generic interface to 13caching backends of any variety, and additionally provides API hooks which 14integrate these cache backends with the locking mechanism of ``dogpile``. 15 16Overall, dogpile.cache is intended as a replacement to the `Beaker 17<https://pypi.org/project/Beaker/>`_ caching system, the internals of which are 18written by the same author. All the ideas of Beaker which "work" are re- 19implemented in dogpile.cache in a more efficient and succinct manner, and all 20the cruft (Beaker's internals were first written in 2005) relegated to the 21trash heap. 22 23Documentation 24------------- 25 26See dogpile.cache's full documentation at 27`dogpile.cache documentation <https://dogpilecache.sqlalchemy.org>`_. The 28sections below provide a brief synopsis of the ``dogpile`` packages. 29 30Features 31-------- 32 33* A succinct API which encourages up-front configuration of pre-defined 34 "regions", each one defining a set of caching characteristics including 35 storage backend, configuration options, and default expiration time. 36* A standard get/set/delete API as well as a function decorator API is 37 provided. 38* The mechanics of key generation are fully customizable. The function 39 decorator API features a pluggable "key generator" to customize how 40 cache keys are made to correspond to function calls, and an optional 41 "key mangler" feature provides for pluggable mangling of keys 42 (such as encoding, SHA-1 hashing) as desired for each region. 43* The dogpile lock, first developed as the core engine behind the Beaker 44 caching system, here vastly simplified, improved, and better tested. 45 Some key performance 46 issues that were intrinsic to Beaker's architecture, particularly that 47 values would frequently be "double-fetched" from the cache, have been fixed. 48* Backends implement their own version of a "distributed" lock, where the 49 "distribution" matches the backend's storage system. For example, the 50 memcached backends allow all clients to coordinate creation of values 51 using memcached itself. The dbm file backend uses a lockfile 52 alongside the dbm file. New backends, such as a Redis-based backend, 53 can provide their own locking mechanism appropriate to the storage 54 engine. 55* Writing new backends or hacking on the existing backends is intended to be 56 routine - all that's needed are basic get/set/delete methods. A distributed 57 lock tailored towards the backend is an optional addition, else dogpile uses 58 a regular thread mutex. New backends can be registered with dogpile.cache 59 directly or made available via setuptools entry points. 60* Included backends feature three memcached backends (python-memcached, pylibmc, 61 bmemcached), a Redis backend, a backend based on Python's 62 anydbm, and a plain dictionary backend. 63* Space for third party plugins, including one which provides the 64 dogpile.cache engine to Mako templates. 65 66 67The SQLAlchemy Project 68---------------------- 69 70Dogpile is part of the `SQLAlchemy Project <https://www.sqlalchemy.org>`_ and 71adheres to the same standards and conventions as the core project. 72 73Development / Bug reporting / Pull requests 74___________________________________________ 75 76Please refer to the 77`SQLAlchemy Community Guide <https://www.sqlalchemy.org/develop.html>`_ for 78guidelines on coding and participating in this project. 79 80Code of Conduct 81_______________ 82 83Above all, SQLAlchemy places great emphasis on polite, thoughtful, and 84constructive communication between users and developers. 85Please see our current Code of Conduct at 86`Code of Conduct <https://www.sqlalchemy.org/codeofconduct.html>`_. 87 88License 89------- 90 91Dogpile is distributed under the `MIT license 92<https://opensource.org/licenses/MIT>`_. 93