From 6451af28fedb7066faaa199107ada44fe317f436 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sat, 14 Apr 2012 18:24:15 -0400 Subject: package reorg cont --- README.rst | 4 ++-- docs/build/api.rst | 18 +++++++++++++----- docs/build/usage.rst | 14 +++++++------- dogpile/core/__init__.py | 4 ++++ 4 files changed, 26 insertions(+), 14 deletions(-) diff --git a/README.rst b/README.rst index e317a85..eeceec6 100644 --- a/README.rst +++ b/README.rst @@ -52,13 +52,13 @@ fall through, and not be blocked. It is expected that the "stale" version of the resource remain available at this time while the new one is generated. -Dogpile is at the core of the `dogpile.cache `_ package +dogpile.core is at the core of the `dogpile.cache `_ package which provides for a basic cache API and sample backends based on the dogpile concept. Development Status ------------------- -Please note Dogpile is new and has only had minimal production usage ! Comments +Please note dogpile.core is new and has only had minimal production usage ! Comments and improvements are welcome. Since this is concurrency-oriented code, please review the source and let me know about potential issues. As always, **use at your own risk!** diff --git a/docs/build/api.rst b/docs/build/api.rst index 57c90d2..408bdde 100644 --- a/docs/build/api.rst +++ b/docs/build/api.rst @@ -2,22 +2,30 @@ API === -dogpile.core -============= +.. currentmodule:: dogpile.core + +Dogpile +======= + +.. autoclass:: Dogpile + :members: + +.. autoclass:: SyncReaderDogpile + :members: -.. automodule:: dogpile.core +.. autoclass:: NeedRegenerationException :members: NameRegistry ============= -.. automodule:: dogpile.core.nameregistry +.. autoclass:: NameRegistry :members: Utilities ========== -.. automodule:: dogpile.core.readwrite_lock +.. autoclass:: ReadWriteMutex :members: diff --git a/docs/build/usage.rst b/docs/build/usage.rst index f069acb..9e93c9a 100644 --- a/docs/build/usage.rst +++ b/docs/build/usage.rst @@ -133,10 +133,10 @@ a second time directly after ``create_and_cache_value()`` has been called. .. _caching_decorator: -Using Dogpile for Caching -========================== +Using dogpile.core for Caching +=============================== -Dogpile is part of an effort to "break up" the Beaker +dogpile.core is part of an effort to "break up" the Beaker package into smaller, simpler components (which also work better). Here, we illustrate how to approximate Beaker's "cache decoration" function, to decorate any function and store the value in @@ -184,18 +184,18 @@ Above we can decorate any function as:: def generate_my_expensive_value(): return slow_database.lookup("stuff") -The Dogpile lock will ensure that only one thread at a time performs ``slow_database.lookup()``, +The :class:`.Dogpile` lock will ensure that only one thread at a time performs ``slow_database.lookup()``, and only every 3600 seconds, unless Memcached has removed the value in which case it will be called again as needed. -In particular, Dogpile's system allows us to call the memcached get() function at most +In particular, dogpile.core's system allows us to call the memcached get() function at most once per access, instead of Beaker's system which calls it twice, and doesn't make us call get() when we just created the value. .. _scaling_on_keys: -Scaling Dogpile against Many Keys -=================================== +Scaling dogpile.core against Many Keys +======================================= The patterns so far have illustrated how to use a single, persistently held :class:`.Dogpile` object which maintains a thread-based lock for the lifespan diff --git a/dogpile/core/__init__.py b/dogpile/core/__init__.py index 49a3b9e..e91889d 100644 --- a/dogpile/core/__init__.py +++ b/dogpile/core/__init__.py @@ -1,4 +1,8 @@ from dogpile import Dogpile, SyncReaderDogpile, NeedRegenerationException +from nameregistry import NameRegistry +from readwrite_lock import ReadWriteMutex + +__all__ = 'Dogpile', 'SyncReaderDogpile', 'NeedRegenerationException', 'NameRegistry', 'ReadWriteMutex' __version__ = '0.3.0' -- cgit v1.2.1