[m-rev.] for review: C# exported proc arguments and documentation

[Julien Fischer]

On Thu, 14 Oct 2010, Peter Wang wrote:

> Branches: main
>
> When a procedure has multiple output arguments, make the exported C# method
> have `out' arguments at the same argument positions as the Mercury procedure.
> (Non-exported procedures have all output arguments at the end of the argument
> list, for reasons described elsewhere.)  When a procedure has a single output
> argument, it is always returned as the method's return value.
>
> Also begin documenting the foreign language interface for C#.
>
> compiler/ml_proc_gen.m:
> compiler/mlds_to_cs.m:
>        As above.
>
> library/rtti_implementation.m:
>        Conform to the change.
>
> doc/reference_manual.texi:
>        Document the foreign language interface for C#.

...

> diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
> index 5896043..07d9ddd 100644
> --- a/doc/reference_manual.texi
> +++ b/doc/reference_manual.texi
> @@ -50,6 +50,7 @@ into another language, under the above conditions for modified versions.
> @author Tyson Dowd
> @author Ralph Becket
> @author Mark Brown
> + at author Peter Wang
> @page
> @vskip 0pt plus 1filll
> Copyright @copyright{} 1995--2010 The University of Melbourne.
> @@ -4894,7 +4895,7 @@ directives that have not yet been executed will not be executed,
> @samp{initialize} is also allowed as a synonym for @samp{initialise}.
>
> Note: @samp{initialise} declarations are currently only supported on
> -the C, Java and Erlang backends.
> +the C, C#, Java and Erlang backends.

That statement made sense when only the C backend supported initialisers
(and likewise the one for finalisers and mutables).  Since all the
usable backends support them I think it can be deleted now.

...

> @menu
> * Using pragma foreign_type for C#	:: Declaring C# types in Mercury
> +* Using pragma foreign_export_enum for C# :: Using Mercury enumerations in C#
> +* Using pragma foreign_enum for C#      :: Assigning Mercury enumerations
> +                                           values in C#
> * Using pragma foreign_proc for C# 	:: Calling C# code from Mercury
> * Using pragma foreign_export for C#    :: Calling Mercury code from C#
> * Using pragma foreign_decl for C# 	:: Including C# declarations in Mercury
> @@ -8004,11 +8124,40 @@ Mercury User's Guide.
> @node Using pragma foreign_type for C#
> @subsubsection Using pragma foreign_type for C#
>
> -There is currently no direct support for using C# types from Mercury;
> -however, the types for IL are compatible with C#, and so the foreign_type
> -support for IL can be used instead.
> -See the section on using pragma foreign_type for IL
> -(@pxref{Using pragma foreign_type for IL}).
> +A C# @samp{pragma foreign_type} declaration has the form:
> +
> + at example
> +:- pragma foreign_type("C#", @var{MercuryTypeName}, "@var{C#-Type}").
> + at end example
> +
> +The @var{C#-Type} can be any accessible C# type.
> +
> +The effect of this declaration is that Mercury values of type
> + at var{MercuryTypeName} will be passed to and from C# foreign_procs
> +as having type @var{C#-Type}.
> +
> +Furthermore, any Mercury procedure exported with @samp{pragma foreign_export}
> +will use @var{C#-Type} as the type for any
> +parameters whose Mercury type is @var{MercuryTypeName}.
> +
> + at node Using pragma foreign_export_enum for C#
> + at subsubsection Using pragma foreign_export_enum for C#
> +
> +For C# the symbolic names generated by a @samp{pragma foreign_export_enum}
> +must form valid C# identifiers.
> +These identifiers are used as the names of static class members.
> +
> +The default mapping used by @samp{pragma foreign_export_enum}
> +declarations for C# is to use the Mercury constructor name as the
> +base of the symbolic name.  For example, the symbolic name for
> +the Mercury constructor @samp{foo} would be @code{foo}.
> +
> + at node Using pragma foreign_enum for C#
> + at subsubsection Using pragma foreign_enum for C#
> +
> +Foreign enumeration values in C# must be a constant value expression
> +which is a valid initializer within an enumeration of underlying
> +type @samp{int}.
>
> @node Using pragma foreign_proc for C#
> @subsubsection Using pragma foreign_proc for C#
> @@ -8023,7 +8172,7 @@ functions declared with @samp{pragma foreign_code}.
> The input and output variables for a C# @samp{pragma foreign_proc} will
> have C# types corresponding to their Mercury types.  The exact rules
> for mapping Mercury types to C# types are described in
> - at ref{IL and C# data passing conventions}.
> + at ref{C# data passing conventions}.
>
> C# code in a @code{pragma foreign_proc} declaration
> for any procedure whose determinism indicates that it can fail
> @@ -8053,7 +8202,33 @@ set @code{SUCCESS_INDICATOR} to false.
> @node Using pragma foreign_export for C#
> @subsubsection Using pragma foreign_export for C#
>
> - at samp{pragma foreign_export} is not currently supported for C#.
> +A @samp{pragma foreign_export} declaration for C# has the form:
> +
> + at example
> +:- pragma foreign_export("C#", @var{MercuryMode}, "@var{C#_Name}").
> + at end example
> +
> +For example,
> +
> + at example
> +:- pragma foreign_export("C#", foo(in, in, out), "FOO").
> + at end example
> +
> +The type signature of the C# interface to a Mercury procedure is as
> +described in @ref{C# data passing conventions}.
> +
> +Calling polymorphically typed Mercury procedures from C# is a little bit more
> +difficult than calling ordinary (monomorphically typed) Mercury procedures.
> +The simplest method is to just create monomorphic forwarding procedures that
> +call the polymorphic procedures, and export them, rather than exporting the
> +polymorphic procedures.
> +
> +If you do export a polymorphically typed Mercury procedure, the compiler
> +will prepend one @samp{type_info} argument to the parameter list of
> +the Java interface function for each polymorphic type variable in the

s/Java/C#/ there.

> +Mercury procedure's type signature.  The caller must arrange to pass
> +in appropriate @samp{type_info} values corresponding to the types
> +of the other arguments passed.
>
> @node Using pragma foreign_decl for C#
> @subsubsection Using pragma foreign_decl for C#

This looks fine 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
--------------------------------------------------------------------------