wrath/shaniqua-plugins
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
dons 2005-12-26 23:15:58 +00:00
parent 92b8dee308
commit 9ee8796e3e
1 changed files with 90 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
docs/hs-plugins.tex
View File

@ -44,18 +44,18 @@ h2 {font-size: 15pt}
\medskip \medskip
% %
{\htmlonly \textbf{Download \endhtmlonly {\htmlonly \textbf{Download \endhtmlonly
\urlh{ftp://ftp.cse.unsw.edu.au/pub/users/dons/hs-plugins/hs-plugins-0.9.10.tar.gz} \urlh{ftp://ftp.cse.unsw.edu.au/pub/users/dons/hs-plugins/hs-plugins-1.0.tar.gz}
{version 0.9.10}} {version 1.0}}
% %
\medskip \medskip
\hsplugins{} is a library for loading code written in Haskell into an \hsplugins{} is a library for loading code written in Haskell into an
application at runtime, in the form of plugins. It also provides a application at runtime, in the form of plugins. It also provides a
mechanism for (re-)compiling Haskell source at runtime. Thirdly, a mechanism for (re-)compiling Haskell source at runtime. Thirdly, a
combination of runtime compilation and dynamic loading provides a set combination of runtime compilation and dynamic loading provides a set of
of \code{eval} functions-- a form of runtime metaprogramming. Values \code{eval} functions-- a form of runtime metaprogramming. Values
exported by Haskell plugins are transparently available to Haskell host exported by Haskell plugins are transparently available to Haskell host
applications, and bindings exist to use Haskell plugins from at least C applications, and bindings exist to use Haskell dynamically in C, Perl
and Objective C programs. \hsplugins{} requires GHC 6.4 or later. and Objective C programs. \hsplugins{} requires GHC 6.4 or later.
\medskip \medskip
@ -72,7 +72,7 @@ and Objective C programs. \hsplugins{} requires GHC 6.4 or later.
\item \item
Download the latest stable release:\\ Download the latest stable release:\\
\url{ftp://ftp.cse.unsw.edu.au/pub/users/dons/hs-plugins/hs-plugins-0.9.10.tar.gz} \url{ftp://ftp.cse.unsw.edu.au/pub/users/dons/hs-plugins/hs-plugins-1.0.tar.gz}
\item \item
Darcs repository of the latest code:\\ Darcs repository of the latest code:\\
@ -107,19 +107,27 @@ Windows.
\section{History} \section{History}
\begin{itemize} \begin{itemize}
\item Jan 2006, v1.0
\begin{itemize}
\item Cabalised build system
\item Behave better on 64 bit platforms
\item Haddock documentation of the API.
\item A couple of bug fixes
\end{itemize}
\item June 2005, v0.9.10 \item June 2005, v0.9.10
\begin{itemize} \begin{itemize}
\item Support for GHC 6.4, with help from Sean \item Support for GHC 6.4, with help from Sean
Seefried for the package.conf parser. Seefried for the package.conf parser.
\item Ported to Windows of various flavours thanks to Vivian McPhail and Shelarcy \item Ported to Windows of various flavours thanks to Vivian McPhail and Shelarcy
\item Removed posix and unix dependencies \item Removed posix and unix dependencies
\item Now uses HSX parser, thanks to Niklas Broberg \item Now uses HSX parser, thanks to Niklas Broberg
\item Extended load interface, thanks to Lemmih \item Extended load interface, thanks to Lemmih
\item Source now in a darcs repository \item Source now in a darcs repository
\item Supports building with GNU make -jN \item Supports building with GNU make -jN
\item Simplified module hierarchy, moved under System.* namespace \item Simplified module hierarchy, moved under System.* namespace
\item pdynload clarifications, thanks to Alistair Bayley \item pdynload clarifications, thanks to Alistair Bayley
\item Miscellaneous bug fixes \item Miscellaneous bug fixes
\end{itemize} \end{itemize}
\item February 2005, v0.9.8 \item February 2005, v0.9.8
@ -287,10 +295,11 @@ The compilation manager fills this role. It is particularly useful in
the implementation of \code{eval}. the implementation of \code{eval}.
The \emph{evaluator}, \code{eval}, utilizes the loader and compilation The \emph{evaluator}, \code{eval}, utilizes the loader and compilation
manager. When passed a string of Haskell code, it compiles the string to manager. When passed a string containing a Haskell expression, it
object code, loads the result, and returns a Haskell value representing compiles the string to object code, loads the result, and returns a
the compiled string to the caller. It can be considered a Haskell Haskell value representing the compiled string to the caller. It can be
interpreter, implemented as a library. considered a Haskell interpreter, implemented as a library, and can be
used to embed Haskell evaluation facilities in an application.
\section{Dynamic Loader} \section{Dynamic Loader}
@ -324,8 +333,8 @@ load_ :: FilePath
\scm{ \scm{
data LoadStatus a data LoadStatus a
= LoadSuccess Module a = LoadSuccess Module a
| LoadFailure Errors | LoadFailure Errors
} }
\end{quote} \end{quote}
% %
@ -352,8 +361,7 @@ failure, or an abstract representation of the module (for calls to
\code{unload} or \code{reload}) with the symbol as a Haskell value. The \code{unload} or \code{reload}) with the symbol as a Haskell value. The
value returned must be given an explicit type signature, or provided value returned must be given an explicit type signature, or provided
with appropriate type constraints such that GHC can determine the with appropriate type constraints such that GHC can determine the
expected type returned by \code{load}, as the return type is notionally expected type returned by \code{load}.
polymorphic.
\code{load\_} is provided for the common situation where no user-defined \code{load\_} is provided for the common situation where no user-defined
package.conf files are required. package.conf files are required.
@ -383,7 +391,6 @@ do mv <- dynload "Plugin.o" ["api"] ["plugins.conf.inplace"] "resource"
\code{dynload} is a safer form of \code{load}. It uses dynamic types \code{dynload} is a safer form of \code{load}. It uses dynamic types
to perform a check on the value returned by \code{load} at runtime, to to perform a check on the value returned by \code{load} at runtime, to
ensure that it has the type the application expects it to have. ensure that it has the type the application expects it to have.
\code{pdynload} is on average 7\% slower than an unchecked load.
In order to use \code{dynload}, the symbol the plugin exports must be In order to use \code{dynload}, the symbol the plugin exports must be
of type \code{AltData.Dynamic:Dynamic}. (See the \code{AltData} library of type \code{AltData.Dynamic:Dynamic}. (See the \code{AltData} library
@ -409,8 +416,8 @@ wrapped inside a rank-N type to hide the polymorphism from the
typechecker. This is a bit cumbersome. An alternative typesafe typechecker. This is a bit cumbersome. An alternative typesafe
\code{load} is available via the \code{pdynload} interface, which is \code{load} is available via the \code{pdynload} interface, which is
able to enforce the type of the plugin using GHC's type inference able to enforce the type of the plugin using GHC's type inference
mechanism, and is not restricted in its expressiveness (at the cost of greater load mechanism, and is not restricted in its expressiveness (at the cost of
times): greater load times):
\begin{quote} \begin{quote}
\scm{ \scm{
@ -554,7 +561,7 @@ Examples:
\begin{quote} \begin{quote}
\scm{ \scm{
do loadPackageWith "yi" ["yi.conf"] do loadPackageWith "yi" ["yi.conf"]
unloadPackage "yi" unloadPackage "yi-0.1"
} }
\end{quote} \end{quote}
@ -895,64 +902,59 @@ mkHsValues :: (Show a) => Data.Map String a -> String
} }
\end{quote} \end{quote}
\end{itemize} \end{itemize}
\subsection{Foreign Eval} % \subsection{Foreign Eval}
%
A preliminary binding to \code{eval} has been implemented to allow C % A preliminary binding to \code{eval} has been implemented to allow C
(and Objective C) programs access to the evaluator. Foreign bindings % (and Objective C) programs access to the evaluator. Foreign bindings
to the compilation manager and dynamic loader are yet to be % to the compilation manager and dynamic loader are yet to be
implemented, but shouldn't be too hard. An foreign binding to a % implemented, but shouldn't be too hard. An foreign binding to a
Haskell module that wraps up calls to \code{make} and \code{load} % Haskell module that wraps up calls to \code{make} and \code{load}
would be fairly trivial. % would be fairly trivial.
%
At the moment we have an ad-hoc binding to \code{eval}, so that C % At the moment we have an ad-hoc binding to \code{eval}, so that C
programmers who know the type of value that will be returned by % programmers who know the type of value that will be returned by
Haskell can call the appropriate hook into the evaluator. If they get % Haskell can call the appropriate hook into the evaluator. If they get
the type wrong, a nullPtr will be returned (so calling Haskell is % the type wrong, a nullPtr will be returned (so calling Haskell is
still typesafe). The foreign bindings to \code{eval} all return % still typesafe). The foreign bindings to \code{eval} all return
\code{NULL} if an error occurred, otherwise a pointer to the value is % \code{NULL} if an error occurred, otherwise a pointer to the value is
returned. % returned.
%
\begin{quote} % \begin{quote}
\scm{ % \scm{
foreign export ccall hs_eval_b :: CString -> IO (Ptr CInt) % foreign export ccall hs_eval_b :: CString -> IO (Ptr CInt)
%
foreign export ccall hs_eval_c :: CString -> IO (Ptr CChar) % foreign export ccall hs_eval_c :: CString -> IO (Ptr CChar)
%
foreign export ccall hs_eval_i :: CString -> IO (Ptr CInt) % foreign export ccall hs_eval_i :: CString -> IO (Ptr CInt)
%
foreign export ccall hs_eval_s :: CString -> IO CString % foreign export ccall hs_eval_s :: CString -> IO CString
} % }
\end{quote} % \end{quote}
%
An example C program for compiling and evaluating Haskell code at % An example C program for compiling and evaluating Haskell code at
runtime follows. This program calculates a fibonacci number, returning % runtime follows. This program calculates a fibonacci number, returning
it as a \code{CString} to the C program: % it as a \code{CString} to the C program:
% % %
\begin{quote} % \begin{quote}
\begin{verbatim} % \begin{verbatim}
#include "EvalHaskell.h" % #include "EvalHaskell.h"
#include <stdio.h> % #include <stdio.h>
%
int main(int argc, char *argv[]) % int main(int argc, char *argv[])
{ % {
char *p; % char *p;
hs_init(&argc, &argv); % hs_init(&argc, &argv);
p = hs_eval_s("show $ let fibs = 1:1:zipWith (+) fibs (tail fibs) in fibs !! 20"); % p = hs_eval_s("show $ let fibs = 1:1:zipWith (+) fibs (tail fibs) in fibs !! 20");
if (p != NULL) % if (p != NULL)
printf("%s\n",p); % printf("%s\n",p);
else % else
printf("error in code\n"); % printf("error in code\n");
hs_exit(); % hs_exit();
return 0; % return 0;
} % }
\end{verbatim} % \end{verbatim}
\end{quote} % \end{quote}
%
\subsection{Notes}
Be careful if you're calling eval from a forked thread. This can
introduce races between the thread and the forked process used by eval
to compile its code.
\section{RTS Binding} \section{RTS Binding}
@ -1657,7 +1659,7 @@ This library is distributed under the terms of the LGPL:
\begin{quote} \begin{quote}
Copyright 2004, Don Stewart - \url{http://www.cse.unsw.edu.au/~dons} Copyright 2003-5, Don Stewart - \url{http://www.cse.unsw.edu.au/~dons}
This library is free software; you can redistribute it and/or This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public modify it under the terms of the GNU Lesser General Public