From 8fd0378c4b87786a03f7b59c8d6c4d6b5afb34b1 Mon Sep 17 00:00:00 2001 From: Greg Weber Date: Wed, 24 Sep 2014 09:04:41 -0700 Subject: [PATCH] TypeCache documentation --- yesod-core/Yesod/Core/TypeCache.hs | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/yesod-core/Yesod/Core/TypeCache.hs b/yesod-core/Yesod/Core/TypeCache.hs index 3b68f8c2..58035db4 100644 --- a/yesod-core/Yesod/Core/TypeCache.hs +++ b/yesod-core/Yesod/Core/TypeCache.hs @@ -1,12 +1,13 @@ -- | a module for caching a monadic action based on its return type -- --- The cache is a HashMap where the key uses the result of typeOf from Typeable. --- The value stored is toDyn from Dynamic to support arbitrary value types. +-- The cache is a HashMap where the key uses the TypeReP from Typeable. +-- The value stored is toDyn from Dynamic to support arbitrary value types in the same Map. -- -- un-exported newtype wrappers should be used to maintain unique keys in the cache. +-- Note that a TypeRep is unique to a module in a package, so types from different modules will not conflict if they have the same name. -- -- used in 'Yesod.Core.Handler.cached' and 'Yesod.Core.Handler.cachedBy' -module Yesod.Core.TypeCache where +module Yesod.Core.TypeCache (cached, cachedBy) where import Prelude hiding (lookup) import Data.Typeable (Typeable, TypeRep, typeOf) @@ -18,16 +19,16 @@ type TypeMap = HashMap TypeRep Dynamic type KeyedTypeMap = HashMap (TypeRep, ByteString) Dynamic -- | avoid performing the same action multiple times. --- Values are stored by their type, the result of typeOf from Typeable. --- Therefore, you should use different newtype wrappers at each cache site. +-- Values are stored by their TypeRep from Typeable. +-- Therefore, you should use un-exported newtype wrappers for each cache. -- -- For example, yesod-auth uses an un-exported newtype, CachedMaybeAuth and exports functions that utilize it such as maybeAuth. -- This means that another module can create its own newtype wrapper to cache the same type from a different action without any cache conflicts. -- --- In Yesod, this is used for a cache that is cleared at the end of every request. +-- In Yesod, this is used for a request-local cache that is cleared at the end of every request. -- See the original announcement: -- --- Since 1.2.0 +-- Since 1.4.0 cached :: (Monad m, Typeable a) => TypeMap -> m a @@ -49,9 +50,9 @@ cached cache action = case clookup cache of cinsert :: Typeable a => a -> TypeMap -> TypeMap cinsert v = insert (typeOf v) (toDyn v) --- | like 'cached'. +-- | similar to 'cached'. -- 'cached' can only cache a single value per type. --- 'cachedBy' stores multiple values per type by usage of a ByteString key +-- 'cachedBy' stores multiple values per type by indexing on a ByteString key -- -- 'cached' is ideal to cache an action that has only one value of a type, such as the session's current user -- 'cachedBy' is required if the action has parameters and can return multiple values per type.