[m-rev.] for review: data passing convention documentation

[Peter Ross]

On Fri, Dec 07, 2001 at 12:23:07PM +1100, Tyson Dowd wrote:
> On 06-Dec-2001, Fergus Henderson <fjh at cs.mu.OZ.AU> wrote:
> > Until the "Foreign language interfacing" chapter is ready for prime time,
> > I'd rather the pointers go in the other direction.  That is, the definitive
> > version should go in the "C interface" chapter and the C language sections of
> > the "Foreign language interfacing" chapter should have pointers to the
> > "C interface" chapter, rather than vice versa.
> 
> I agree with this too.  We are not yet ready to make the Foreign
> language interfacing chapter the main one -- if you do that, we will
> have to support it, and it will be a bit harder to make breaking
> changes.
> 
Done.



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


Estimated hours taken: 0.1
Branches: main

doc/reference_manual.texi:
    Move the documentation about passing data to and from C back into
    the section about the C interfacing, as suggested by trd and fjh.


Index: reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.232
diff -u -r1.232 reference_manual.texi
--- reference_manual.texi	7 Dec 2001 11:13:35 -0000	1.232
+++ reference_manual.texi	7 Dec 2001 11:23:45 -0000
@@ -5022,70 +5022,7 @@
 @node C language
 @subsection C language
 
-For each of the Mercury types @code{int}, @code{float}, @code{char},
-and @code{string}, there is a C typedef for the corresponding type in C:
- at code{MR_Integer}, @code{MR_Float}, @code{MR_Char},
-and @code{MR_String} respectively.
-
-In the current implementation, @samp{MR_Integer} is a typedef for an
-integral type whose size is the same size as a pointer; @samp{MR_Float} is
-a typedef for @samp{double} (unless the program and the Mercury library
-was compiled with @samp{-DUSE_SINGLE_PREC_FLOAT}, in which case it is
-a typedef for @samp{float}); @samp{MR_Char} is a typedef for @samp{char};
-and @samp{MR_String} is a typedef for @samp{MR_Char *}.
-
-Mercury variables of type @code{int}, @code{float}, @code{char}, or
- at code{string} are passed to and from C as C variables whose type is
-given by the corresponding typedef.  Mercury variables of any other
-type are passed as a @samp{MR_Word}, which in the current implementation
-is a typedef for an unsigned type whose size is the same size as a pointer.
-(Note: it would in fact be better for each Mercury type to map to a distinct
-abstract type in C, since that would be more type-safe, and thus we may
-change this in a future release.  We advise programmers who are manipulating
-Mercury types in C code to use typedefs for each user-defined Mercury type,
-and to treat each such type as an abstract data type.  This is good style
-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.
-
- at c For the Managed C++ interface, the types are mapped slightly differently:
- at c Mercury variables which are polymorphically typed
- at c have type @samp{MR_Box} rather than @samp{MR_Word}.
- at c XXX We should document the Managed C++ interface somewhere.
-
-Mercury lists can be manipulated by C code using the following macros,
-which are defined by the Mercury implementation.
-
- at example
-MR_list_is_empty(list)     /* test if a list is empty */
-MR_list_head(list)         /* get the head of a list */
-MR_list_tail(list)         /* get the tail of a list */
-MR_list_empty()            /* create an empty list */
-MR_list_cons(head,tail)    /* construct a list with the given head and tail */
- at end example
-
-Note that the use of these macros is subject to some caveats
-(@pxref{Memory management}).
+This section is currently documented in @pxref{Passing data to and from C}.
 
 @node IL language
 @subsection IL language
@@ -6134,7 +6071,70 @@
 @node Passing data to and from C
 @section Passing data to and from C
 
-This section has moved to @pxref{C language}.
+For each of the Mercury types @code{int}, @code{float}, @code{char},
+and @code{string}, there is a C typedef for the corresponding type in C:
+ at code{MR_Integer}, @code{MR_Float}, @code{MR_Char},
+and @code{MR_String} respectively.
+
+In the current implementation, @samp{MR_Integer} is a typedef for an
+integral type whose size is the same size as a pointer; @samp{MR_Float} is
+a typedef for @samp{double} (unless the program and the Mercury library
+was compiled with @samp{-DUSE_SINGLE_PREC_FLOAT}, in which case it is
+a typedef for @samp{float}); @samp{MR_Char} is a typedef for @samp{char};
+and @samp{MR_String} is a typedef for @samp{MR_Char *}.
+
+Mercury variables of type @code{int}, @code{float}, @code{char}, or
+ at code{string} are passed to and from C as C variables whose type is
+given by the corresponding typedef.  Mercury variables of any other
+type are passed as a @samp{MR_Word}, which in the current implementation
+is a typedef for an unsigned type whose size is the same size as a pointer.
+(Note: it would in fact be better for each Mercury type to map to a distinct
+abstract type in C, since that would be more type-safe, and thus we may
+change this in a future release.  We advise programmers who are manipulating
+Mercury types in C code to use typedefs for each user-defined Mercury type,
+and to treat each such type as an abstract data type.  This is good style
+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.
+
+ at c For the Managed C++ interface, the types are mapped slightly differently:
+ at c Mercury variables which are polymorphically typed
+ at c have type @samp{MR_Box} rather than @samp{MR_Word}.
+ at c XXX We should document the Managed C++ interface somewhere.
+
+Mercury lists can be manipulated by C code using the following macros,
+which are defined by the Mercury implementation.
+
+ at example
+MR_list_is_empty(list)     /* test if a list is empty */
+MR_list_head(list)         /* get the head of a list */
+MR_list_tail(list)         /* get the tail of a list */
+MR_list_empty()            /* create an empty list */
+MR_list_cons(head,tail)    /* construct a list with the given head and tail */
+ at end example
+
+Note that the use of these macros is subject to some caveats
+(@pxref{Memory management}).
 
 @node Using C pointers
 @section Using C pointers

--------------------------------------------------------------------------
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
--------------------------------------------------------------------------