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

[Peter Ross]

Hi,


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


Estimated hours taken: 1
Branches: main

doc/reference_manual.texi:
    Reorganise the documentation about the data passing
    conventions so that it is all located in one spot.

Index: reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.228
diff -u -r1.228 reference_manual.texi
--- reference_manual.texi	22 Nov 2001 19:19:54 -0000	1.228
+++ reference_manual.texi	3 Dec 2001 12:33:50 -0000
@@ -4815,6 +4815,8 @@
 				       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.
@@ -5004,6 +5006,82 @@
 
 @c -----------------------------------------------------------------------
 
+ at node Data passing conventions
+ at section Data passing conventions
+
+Each backend will have its own conventions for passing data.
+
+ at menu
+* C backend	:: Data passing convention for the C backend.
+* IL backend	:: Data passing convention for the IL backend.
+ at end menu
+
+ at node C backend
+ at subsection C backend
+
+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.)
+
+ 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}).
+
+ at node IL backend
+ at subsection IL backend
+
+The Mercury types @code{int}, @code{float}, @code{char},
+and @code{string} are mapped to the Common Language Runtime types 
+ at code{System.Int32}, @code{System.Double}, @code{System.Char} and
+ at code{System.String} respectively.
+
+Mercury variables which are polymorphically typed (e.g. whose type is a 
+type variables) will be passed as @code{System.Object} while all other
+Mercury variables are passed as @code{System.Object[]}.
+This mapping is subject to change and you should try to avoid writing
+code that relies heavily upon a particular representation of Mercury
+terms.
+
+ at c XXX foreign type should be documented here.
+
+ at c -----------------------------------------------------------------------
+
 @node Adding foreign declarations
 @section Adding foreign declarations
 
@@ -5133,7 +5211,7 @@
 
 The input and output variables will have C types corresponding
 to their Mercury types, as determined by the rules specified in
- at ref{Passing data to and from C}.
+ at ref{C backend}.
 
 The C code fragment may declare local variables, but it should not
 declare any labels or static variables unless there is also a Mercury
@@ -5340,17 +5418,13 @@
 @c If the procedure fails, the IL code need only
 @c set @code{success} to false (zero).
 
-The Mercury types @code{int}, @code{float}, @code{char},
-and @code{string} are mapped to the Common Language Runtime types 
- at code{int32}, @code{float64}, @code{char} and @code{System.String}
-respectively.
-
-Mercury variables which are polymorphically typed (e.g. whose type is a 
-type variables) will be passed as @code{System.Object} while all other
-Mercury variables are passed as @code{System.Object[]}.
-This mapping is subject to change and you should try to avoid writing
-code that relies heavily upon a particular representation of Mercury
-terms.
+Each of the head variables will be represented by the Common Language
+Runtime types as specified in @pxref{IL backend}.
+Note that in IL assembler the types
+ at samp{System.Int32}, @samp{System.Double}, @samp{System.Char}
+and @samp{System.String}
+are represented by 
+ at samp{int}, @samp{float64}, @samp{char} and @samp{string}.
 
 @node Using pragma foreign_decl for IL
 @subsubsection Using pragma foreign_decl for IL
@@ -6014,49 +6088,7 @@
 @node Passing data to and from C
 @section Passing data to and from C
 
-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.)
-
- 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 has moved to @pxref{C backend}.
 
 @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
--------------------------------------------------------------------------