[m-dev.] for discussion: pragma foreign_import

[Peter Ross]

Here is the relative diff with fjh's review comments applied,
plus changing to using method reference syntax.

diff -u reference_manual.texi reference_manual.texi
--- reference_manual.texi
+++ reference_manual.texi
@@ -4815,8 +4815,6 @@
 				       or function as a call to code
 				       written in a different
 				       programming language.
-* Data passing conventions::	       How Mercury types are represented
-				       on the various backends.
 * Adding foreign declarations::        How to add declarations of
   				       entities in other programming
 				       languages.
@@ -4845,7 +4843,7 @@
 code using @samp{pragma foreign_proc}.
 
 @menu
-* pragma foreign_import::       Importing foreign functions.
+* pragma foreign_import::       Importing foreign procedures.
 * pragma foreign_proc::         Defining Mercury procedures using foreign code.
 * Foreign code attributes::   	Describing properties of foreign
 				functions or code.
@@ -4863,13 +4861,13 @@
 or
 
 @example
-:- pragma import(@var{Lang},
+:- pragma foreign_import(@var{Lang},
 		@var{Func}(@var{Mode1}, @var{Mode2}, @dots{}) = @var{Mode},
 		@var{Attributes}, "@var{Name}").
 @end example
 
 @noindent
-imports a function in the foreign language specified by @var{Lang}
+imports a procedure in the foreign language specified by @var{Lang}
 for use by Mercury.
 @var{Pred} or @var{Func} must specify the name of a previously declared
 Mercury predicate or function, and @var{Mode1}, @var{Mode2}, @dots{},
@@ -4877,42 +4875,28 @@
 modes of that predicate or function.
 There must be no clauses for the specified Mercury procedure;
 instead, any calls to that procedure will be executed by calling
-the function specified by @var{Name}.
+the foreign language procedure specified by @var{Name}.
 The @var{Attributes} argument is optional; if present,
-it specifies properties of the given function
+it specifies properties of the given procedure
 (@pxref{Foreign code attributes}).
 
 The interface to the function for a given Mercury procedure is
-determined as follows.
-Mercury types are converted to foreign types according to the rules in
- at ref{Data passing conventions}.
-Mercury arguments declared with input modes
-are passed by value to the function.
-Mercury arguments declared with output modes
-are passed by reference.
- at c XXX I think we make this a bool on the IL backend.
-If the Mercury procedure can fail, then its imported function should return
-a Mercury integer indicating success or failure:
-non-zero indicates success, and zero indicates failure.
-If the Mercury procedure is a Mercury function that cannot fail, and
-the function result has an output mode, then the foreign function should
-return the Mercury function result value.
-Otherwise the function result is appended as an extra argument.
-Arguments of type @samp{io__state} or @samp{store__store(_)} are not
-passed at all; that's because these types represent mutable state, and
-in foreign functions modifications to mutable state are done via side effects,
-rather than argument passing.
+determined as explained in @ref{Data passing conventions}.
 
 If you use @samp{pragma foreign_import} for a polymorphically typed
 Mercury procedure,
 the compiler will prepend one @samp{type_info} argument to the parameters
-passed to the C function for each polymorphic type variable in the
-Mercury procedure's type signature.  The values passed in these arguments
-will be the same as the values that would be obtained using the Mercury
- at samp{type_of} function in the Mercury standard library module @samp{std_util}.
-These values may be useful in case the C function wishes to in turn call
-another polymorphic Mercury procedure (@pxref{Calling Mercury code from C}).
- at c XXX we need a calling Mercury code from the outside world section.
+passed to the foreign language procedure for each polymorphic type
+variable in the Mercury procedure's type signature.
+The values passed in these arguments will be the same as the values that
+would be obtained using the Mercury @samp{type_of} function in the
+Mercury standard library module @samp{std_util}.
+These values may be useful in case the foreign language function wishes
+to in turn call another polymorphic Mercury procedure (@pxref{Calling
+Mercury code from C}).
+
+ at c XXX we need a calling Mercury code from the outside world section,
+ at c not just from C.
 
 You may not give a @samp{pragma foreign_import} declaration for a procedure
 with determinism @samp{nondet} or @samp{multi}.
@@ -4935,8 +4919,7 @@
 
 To import an IL function on the IL backend
 use @code{il} for @var{Lang},
- at c XXX suggestions on how to say this better
-and @var{Name} is the IL declaration for the IL function.
+and @var{Name} is the IL syntax for class method references.
 
 For example, the following code imports the IL function @samp{Cos()}
 as the Mercury function @samp{cos/1}:
@@ -4944,7 +4927,7 @@
 @example
 :- func cos(float) = float.
 :- pragma foreign_import(il, cos(in) = out,
-		".method public static float64 Cos(float64)"
+		"static float64 [mscorlib]System.Math.Cos(float64)"
 @end example
 
 @node pragma foreign_proc
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------