[m-rev.] Re: [m-dev.] for discussion: pragma foreign_import

[Peter Ross]

On Tue, Dec 04, 2001 at 12:09:31PM +1100, Fergus Henderson wrote:
> On 03-Dec-2001, Peter Ross <peter.ross at miscrit.be> wrote:
> > +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.
> 
> This is really language-specific.  The section on "Data passing
> conventions" is part of the C interface documentation and only describes
> what happens for the C interface, not for other languages.
> And output arguments will definitely not be passed by reference for the
> Java interface, for example.
> 
> Same applies to the remainder of this section,
> e.g. the comments about io__states not being passed
> because I/O is done via side effects should not be
> true for the Haskell or Clean interface.
> 
> The semantics need to be divided into language-specific and
> language-independent parts.
> 
Here is a diff which does just that.

This is a diff against the main branch, I have submited this change as a
seperate change as it is essentially just reorganisation of the
documentation.

===================================================================


Estimated hours taken: 0.25
Branches: main

reference_manual.texi:
    Move sections on how to convert the Mercury parameter passing
    convention to the backend parameter passing convention to each of
    the C an IL backend subsections of the `Data passing convention'
    section.


Index: reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.229
diff -u -r1.229 reference_manual.texi
--- reference_manual.texi	4 Dec 2001 11:11:59 -0000	1.229
+++ reference_manual.texi	4 Dec 2001 13:43:47 -0000
@@ -5009,7 +5009,10 @@
 @node Data passing conventions
 @section Data passing conventions
 
-Each backend will have its own conventions for passing data.
+For each backend,
+we explain how to map a Mercury type to a type on the backend.
+We also map the Mercury parameter passing convention
+to the backend parameter passing convention.
 
 @menu
 * C backend	:: Data passing convention for the C backend.
@@ -5044,6 +5047,27 @@
 and it will also minimize any compatibility problems if and when we do change
 this.)
 
+Mercury arguments declared with input modes are passed by value to the
+C function.
+For output arguments,
+the Mercury implementation will pass to the C function an address in
+which to store the result. 
+If the Mercury procedure can fail,
+then its C function should return a truth value of type
+ at samp{MR_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 C 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 C modifications to mutable state are done via side effects,
+rather than argument passing.
+
+ at c XXX foreign type should be documented here.
+
 @c For the Managed C++ interface, the types are mapped slightly differently:
 @c Mercury variables which are polymorphically typed
 @c have type @samp{MR_Box} rather than @samp{MR_Word}.
@@ -5078,6 +5102,25 @@
 code that relies heavily upon a particular representation of Mercury
 terms.
 
+Mercury arguments declared with input modes are passed by value to the
+IL function.
+For output arguments,
+the Mercury implementation will pass to the IL function a reference to
+the location in which to store the result. 
+If the Mercury procedure can fail,
+then its IL function should return a truth value of type
+ at samp{System.Bool} indicating success or failure:
+ at code{true} indicates success, and @code{false} indicates failure.
+If the Mercury procedure is a Mercury function that cannot fail,
+and the function result has an output mode,
+then the IL 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 IL
+modifications to mutable state are done via side effects,
+rather than argument passing.
+
 @c XXX foreign type should be documented here.
 
 @c -----------------------------------------------------------------------
@@ -5562,22 +5605,8 @@
 @end example
 
 The interface to the C function for a given Mercury procedure is
-determined as follows.  Mercury types are converted to C types
-according to the rules in @ref{Passing data to and from C}.
-Mercury arguments declared with input modes are passed by value to the
-C function.  For output arguments, the Mercury implementation will pass
-to the C function an address in which to store the result. 
-If the Mercury procedure can fail, then its C function should return a
-truth value of type @samp{MR_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 C 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 C modifications to mutable state are done via side effects, rather
-than argument passing.
+determined as follows.  Mercury types are converted to C types and
+passed according to the rules in @ref{Passing data to and from C}.
 
 If you use @samp{pragma import} for a polymorphically typed Mercury procedure,
 the compiler will prepend one @samp{type_info} argument to the parameters

--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------