% $Id: persistentRemember.tex,v 1.1.1.5 2004/10/16 15:16:58 nthiery Exp $
\begin{Mhelppage}{persistentRemember}{N.~Thiéry}
  [ImplState=stable,TestState=stable,DocState=stable]
%\Mproofread{user}{date}{comment}

\begin{MInfo}
  \eng{functions with persistent remember table}
\end{MInfo}

\MDeclareOption{\Recalculate}{Recalculate}

\begin{MIntro}
  \eng{The domain \Mthis{} provides tools to define functions with a
    remember table which persists between \mupad{} sessions.}
\end{MIntro}

\begin{MDomElConst}
  \MCall{f}
%  \MCall{}
\end{MDomElConst}

\begin{MParameters}
  \param{f}%
  \eng{The function which is to be called to calculate the result when
    it is not yet in the database.}
\end{MParameters}

\begin{MDetails}
  \eng{Objects of the domain \Mthis{} are functions which remember
    their result not only from one call to another (as with the
    standard \Mup{remember} option), but also from one MuPAD session
    to another.}
  
  \eng{This is implemented by storing the result in a database of
    files.  The database is organized as follow. There is a main
    directory (by default \Mex{".persistentRememberDataBase} in the
    current directory). To each function of this domain is associated
    a subdirectory (by default the \mupad{} name of the function).
    Finally, for each set of arguments, the result is stored in a
    plain text file in this subdirectory whose name is obtained by
    adding a ".mu" suffix to an md5 128 bits hexadecimal fingerprint
    of the textual representation of the arguments.}
  
  \eng{\Mup{expr2text} and \Mup{fread} are used to convert objects to
    and from textual representations. So, this package only works
    correctly with objects \Mex{x} whose domain implement
    \Mup{expr2text} properly (that is \Mex{text2expr(expr2text(x))}
    recreates an object strictly equivalent to \Mex{x}).}
\end{MDetails}


\begin{MDomEntries}
  \MDomEntry{directory}
  \eng{the main directory of the database.}
\end{MDomEntries}

\begin{MExample}{ex-basic}
  \eng{We create a function \Mex{g} in this domain:}
  % Cleanup the persistent remember directory
  \begin{Mvin}{hide=true}
operators::persistentRemember::resetDirectory():
  \end{Mvin}
  \begin{Mvout}{hide=true}
  \end{Mvout}
  \begin{Mexin}
f := proc(x) begin print(coucou); x^2; end:
g := operators::persistentRemember(f):
  \end{Mexin}
  \begin{Mexout}
  \end{Mexout}
  \eng{The first time, \Mex{g(2)} is called, the calculation is
  delegated to \Mex{f(2)}:}
  \begin{Mexin}
g(2)
  \end{Mexin}
  \begin{Mexout}
                            coucou

                               4
  \end{Mexout}
  \eng{Later on, the result is fetched from the database:}
  \begin{Mexin}
g(2)
  \end{Mexin}
  \begin{Mexout}
                               4
  \end{Mexout}
\end{MExample}

\begin{MExample}{ex-traps}
  \eng{One has to be careful with some obvious traps. First of all,
    redefining the internal function does not clear the persistent
    remember table. Here, the result of \Mex{g(2)} is still \Mex{4}
    even if \Mex{f} has changed:}
  \begin{Mexin}
f := x->x^3:
g := operators::persistentRemember(f):
g(2)
  \end{Mexin}
  \begin{Mexout}
                               4
  \end{Mexout}
  
  \eng{Also, beware of domains that do not have a proper
    implementation of expr2text:}
  \begin{Mexin}
Z4 := Dom::IntegerMod(4):
f2 := x->x^2:
g := operators::persistentRemember(f2):
g(Z4(3)), g(Z4(3));
  \end{Mexin}
  \begin{Mexout}
                          1 mod 4, 1
  \end{Mexout}
  The first time \Mex{g} was called, the result was computed properly and
  stored in the file using \Mex{expr2text}. The second time, the result was
  reread from the file; however this did not create back an element of
  \Mex{Z4} as desired because the textual representation of
  \Mex{Z4(3)}  does not contain all the required information for this:
  \begin{Mexin}
x := Z4(5); expr2text(x); bool(x = text2expr(expr2text(x)));
  \end{Mexin}
  \begin{Mexout}
                            1 mod 4

                           "1 mod 4"

                             FALSE
  \end{Mexout}
  % Cleanup the persistent remember directory
  \begin{Mvin}{hide=true}
operators::persistentRemember::resetDirectory():
  \end{Mvin}
  \begin{Mvout}{hide=true}
  \end{Mvout}
\end{MExample}

%\begin{MBackground}
%\end{MBackground}

\begin{MChanges}
  \version{3}%
  \eng[New library]{\Mthis{} is a new library} %
\end{MChanges}

\end{Mhelppage}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: main
%%% TeX-master: t
%%% End: 
