_Chapter_Caches.xml

<?xml version="1.0" encoding="UTF-8"?>

<!-- This is an automatically generated file. -->
<Chapter Label="Chapter_Caches">
<Heading>Caches</Heading>

<Section Label="Chapter_Caches_Section_Object_constructors">
<Heading>Object constructors</Heading>

Caches are objects which store for a fixed number of keys
a value, so they are a map Obj^k -> Obj, while the k is
fixed. A cache ususally stores the result in a weak pointer
list, which means that if the value which the cache should store
is not referenced in the system anymore, it will not be remembered
by the cache. However, caches can be set to store the value permanently (crisp),
or not to store any new value at all (inaktive). In that case, already stored values
are still in the cache and can be accessed once the cache is set active again.
<ManSection Label="AutoDoc_generated_group1">
  <Oper Arg="[k],[is_crisp]" Name="CachingObject" />
  <Oper Arg="arg" Name="CachingObject" Label="for IsObject"/>
  <Oper Arg="arg1,arg2" Name="CachingObject" Label="for IsObject, IsObject"/>
 <Returns>a cache
</Returns>
 <Description>
If no argument is given, the function returns a weak cache with key length one,
if an integer k is given, a weak cache with key length k, and if the bool is_crisp
is true, a crisp cache with the corresponding length.
<P/>
 </Description>
</ManSection>


<P/>
<ManSection Label="AutoDoc_generated_group2">
  <Oper Arg="object, cache_name, length, [is_crisp]" Name="CachingObject" Label="for IsObject, IsObject, IsInt"/>
  <Oper Arg="arg1,arg2,arg3,arg4" Name="CachingObject" Label="for IsObject, IsObject, IsInt, IsBool"/>
 <Description>
This methods are not installed, they serve as an interface
for InstallMethodWithCacheFromObject.
<P/>
 </Description>
</ManSection>


<P/>
</Section>


<Section Label="Chapter_Caches_Section_Setters_getters">
<Heading>Setters, getters</Heading>

<ManSection>
  <Oper Arg="cache, key" Name="CacheValue" Label="for IsCachingObject, IsObject"/>
 <Returns>stored value
</Returns>
 <Description>
If there is a value stored in the cache for key, which can be a single key for
caches with key length one or a list of keys depending on the key length of the cache,
this method returns a list only contraining the value, otherwise an empty list.
 </Description>
</ManSection>


<ManSection>
  <Oper Arg="cache, key, value" Name="SetCacheValue" Label="for IsCachingObject, IsObject, IsObject"/>
 <Description>
Sets the value of key of the cache to value.
 </Description>
</ManSection>


<ManSection>
  <Oper Arg="obj1, obj2" Name="IsEqualForCache" Label="for IsObject, IsObject"/>
 <Returns>true or false
</Returns>
 <Description>
This function is used to compare objects for the caches.
The standard way is IsIdenticalObj, and lists are compared recursive
with this function. It is possible and recommended to overload this function as needed.
 </Description>
</ManSection>


</Section>


<Section Label="Chapter_Caches_Section_Managing_functions">
<Heading>Managing functions</Heading>

<ManSection>
  <Func Arg="cache" Name="SetCachingObjectCrisp" />
 <Returns>nothing
</Returns>
 <Description>
Sets the caching to crisp, weak, or deativates the cache completely.
 </Description>
</ManSection>


<P/>
<ManSection>
  <Func Arg="arg" Name="SetCachingObjectWeak" />
 <Description>
<P/>
 </Description>
</ManSection>


<P/>
<ManSection>
  <Func Arg="arg" Name="DeactivateCachingObject" />
 <Description>
<P/>
 </Description>
</ManSection>


</Section>


<Section Label="Chapter_Caches_Section_Install_functions">
<Heading>Install functions</Heading>

<ManSection>
  <Func Arg="Like InstallMethod" Name="InstallMethodWithCache" />
 <Description>
Installs a method like InstallMethod, but additionally puts a cache layer around it
so that the result is cached. It is possible to give the cache as the option Cache,
to use the same cache for more than one method or store it somewhere to have access to
the cache.
 </Description>
</ManSection>


<ManSection>
  <Func Arg="arg" Name="InstallMethodWithCrispCache" />
 <Description>
Like InstallMethodWithCache, but with a crisp cache.
 </Description>
</ManSection>


<ManSection>
  <Func Arg="Like InstallMethod" Name="InstallMethodWithCacheFromObject" />
 <Description>
This works just like InstallMethodWithCache, but it extracts
the cache via the CachingObject method from one of its arguments.
The CachingObject must then be implemented for one of the arguments,
and the option ArgumentNumber can specify which option to be used.
As second argument for CachingObject a string is used, which can identify
the cache. Standard is the name of the operation, for which the method is
installed, but it can be specified using the CacheName option.
 </Description>
</ManSection>


<ManSection>
  <Func Arg="func" Name="FunctionWithCache" />
 <Returns>a function
</Returns>
 <Description>
Creates a cached function out of a given function <A>func</A>.
If the option Cache is a cache, this cache is used. If the option
Cache is the string crisp, a crisp cache is used. All other values for this option
lead to a single weak cache.
 </Description>
</ManSection>


</Section>


</Chapter>