[m-rev.] for review (needs committing): Document and fix pragma foreign_export("IL")

[Julien Fischer]

On Fri, 29 Dec 2006, Jonathan Morgan wrote:

> Estimated hours taken: 6
> Branches: main
>
> Document `:- pragma foreign_export' for the IL foreign language (this
> had previously been implemented for `:- pragma export').

Delete the bit in parentheses - it reads as though we previously had
documentation for pragma export for IL (which we didn't).

> Make the
> MLDS filter foreign exports by foreign language (this is not a problem

I suggest:

 	Make the MLDS backend filter out those foreign_export pragmas
 	that are not supported by the current compilation target.

> for the other backends, as they only have one foreign language).

You can omit the stuff about the other backends; it would be a problem
for them if they supported more than one foreign language but it would
also be a problem that would need to be handled in a different spot.

> Remove warnings and todos associated with this.
>
> Add IL foreign exports for all the existing C foreign exports, to
> restore the backend to the same state as it was in before pragma
> foreign_export was implemented.  (Note that the IL standard library
> usage should be reviewed after `pragma foreign_export' is implemented
> for C#).
>
> compiler/foreign.m:
> compiler/ml_code_gen.m:
>   For any given foreign language, only include those `pragma
> foreign_exports' that have the given target language.

I suggest:

 	Only include those foreign_export pragmas that are compatible with
 	the target language.

> compiler/add_pragma.m:
> compiler/mlds_to_il.m:
>   Remove warnings.

For mlds_to_il.m you've updated a comment, you haven't removed any
warnings.

> library/*.m:
>   Add a foreign_export("IL") for every existing foreign_export("C").

While that won't hurt it's probably unnecssary in a lot of cases - a lot
of the existing ones are just for use by the debugger (which the .NET
backend won't support anytime soon) and a lot of them are just simply
unused.  (I wouldn't bother changing anything - as you said it will
need to be revised when foreign_export is supported with C#.)

>   Convert a couple of `pragma export' statements to `pragma foreign_export'.
>
> doc/reference_manual.texi:
>   Document `pragma foreign_export` for the IL foreign language.
>

...

> Index: compiler/foreign.m
> ===================================================================
> RCS file: /home/mercury1/repository/mercury/compiler/foreign.m,v
> retrieving revision 1.67
> diff -u -r1.67 foreign.m
> --- compiler/foreign.m	2 Oct 2006 05:21:10 -0000	1.67
> +++ compiler/foreign.m	29 Dec 2006 10:57:42 -0000
> @@ -112,6 +112,15 @@
> :- pred filter_bodys(foreign_language::in, foreign_body_info::in,
>    foreign_body_info::out, foreign_body_info::out) is det.
>
> +    % Filter the foreign exports for the given foreign language.
> +    % The first return value is the list of matches, the second is
> +    % the list of mis-matches.
> +    %
> +:- pred filter_exports(foreign_language::in,
> +    list(pragma_exported_proc)::in,
> +    list(pragma_exported_proc)::out, list(pragma_exported_proc)::out)
> +    is det.

In general the first argument of that predicate should be a list
of foreign languages, i.e. all the ones that are supported as export
languages for this particular target.

>    % Given some foreign code, generate some suitable proxy code for
>    % calling the code via one of the given languages.
>    % This might mean, for example, generating a call to a
> @@ -193,6 +202,11 @@
>    IsWanted = (pred(foreign_body_code(Lang, _, _)::in) is semidet :-
>        WantedLang = Lang),
>    list.filter(IsWanted, Bodys0, LangBodys, NotLangBodys).
> +
> +filter_exports(WantedLang, Exports0, LangExports, NotLangExports) :-
> +    IsWanted = (pred(pragma_exported_proc(Lang, _, _, _, _)::in) is semidet 
> :-
> +        WantedLang = Lang),
> +    list.filter(IsWanted, Exports0, LangExports, NotLangExports).
>
> extrude_pragma_implementation([], _PragmaVars, _PredName, _PredOrFunc,
>        _Context, !ModuleInfo, !NewAttributes, !Impl) :-

...

> Index: doc/reference_manual.texi
> ===================================================================
> RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
> retrieving revision 1.373
> diff -u -r1.373 reference_manual.texi
> --- doc/reference_manual.texi	4 Dec 2006 04:30:50 -0000	1.373
> +++ doc/reference_manual.texi	29 Dec 2006 10:58:35 -0000
> @@ -7399,7 +7399,54 @@
> @node Using pragma foreign_export for IL
> @subsubsection Using pragma foreign_export for IL
>
> - at samp{pragma foreign_export} is currently not supported for IL.
> +A @samp{pragma foreign_export} declaration for IL has the form:
> +
> + at example
> +:- pragma foreign_export("IL", @var{MercuryMode}, "@var{IL_Name}").
> + at end example
> +
> +For example,
> +
> + at example
> +:- pragma foreign_export("IL", foo(in, in, out), "foo").
> + at end example
> +
> +For each Mercury module containing @samp{pragma foreign_export} declarations
> +for IL, the Mercury implementation will automatically create a static method
> + at var{IL_Name}() in the <module_name>.mercury_code class for each of the
> + at samp{pragma foreign_export} declarations.

> + Each such IL method is the
> +.NET interface to the specified Mercury procedure, and should be usable from

s/the .NET interface/a .NET interface/ since presumably any C# or MC++
exports for the same procedure would also consistitute a .NET interface to
it.

> +any .NET language.
> +
> +The type signature of the IL interface to a Mercury procedure is determined 
> as
> +follows.  Mercury types are converted to IL types according to the rules in
> + at ref{IL and C# data passing conventions}.  Input arguments are passed by 
> value.
> +For output arguments, the caller must pass the address in which to store the
> +result.  If the Mercury procedure can fail, then its IL interface method
> +returns a truth value indicating success or failure.  If the Mercury 
> procedure
> +is a Mercury function that cannot fail, and the function result has an 
> output
> +mode, then the IL interface method will return the Mercury function result
> +value.  Otherwise the function result is appended as an extra argument.

That looks okay otherwise.

Julien.
--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------