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