[m-rev.] for review: il as a foreign language

[Fergus Henderson]

On 17-Jul-2001, Tyson Dowd <trd at cs.mu.OZ.AU> wrote:
> 
> Ok, here's a relative diff of the suggestions you made. 

I can see that I didn't explain my suggestions clearly enough.
This diff moved almost the entire description of interfacing with C
using the new foreign language interface into the user guide,
which was *not* what I wanted.

The language reference manual should describe the syntax and semantics
of everything that goes in Mercury source files.  This *includes*
implementation-specific language extensions, although should be carefully
identified as such.

The user guide should describe other aspects of the Mercury implementation
and development environment, including compiler options, the different back-ends,
what goes in Mmakefiles, and so on.

All of the stuff quoted below is talking about the syntax or semantics of
constructs that go in Mercury source files, so it should go in the language
reference manual, not the user guide.

> +++ doc/user_guide.texi	2001/07/17 09:43:57
...
> + at node Interfacing with C
> + at section Interfacing with C
> +
> + at menu
> +* Using pragma foreign_proc for C 	:: Calling C code from Mercury
> +* Using pragma foreign_decl for C 	:: Including C declarations in Mercury
> +* Using pragma foreign_code for C 	:: Including C code in Mercury
> + at end menu
> +
> + at node Using pragma foreign_proc for C
> + at subsection Using pragma foreign_proc for C
> +
> +The input and output variables will have C types corresponding
> +to their Mercury types, as determined by the rules specified in
> +``Passing data to and from C'' in the ``C Interface''
> +chapter of the Mercury Language Reference Manual.
> +
> +The C code fragment may declare local variables, but it should not
> +declare any labels or static variables unless there is also a Mercury
> + at samp{pragma no_inline} declaration for the procedure.
> +The reason for this is that otherwise the Mercury implementation may
> +inline the procedure by duplicating the C code fragment for each call.
> +If the C code fragment declared a static variable, inlining it in this
> +way could result in the program having multiple instances of the static
> +variable, rather than a single shared instance.  If the C code fragment
> +declared a label, inlining it in this way could result in an error due
> +to the same label being defined twice inside a single C function.
> +
> +C code in a @code{pragma foreign_proc} declaration
> +for any procedure whose determinism indicates that it could fail
> +must assign a truth value to the macro @samp{SUCCESS_INDICATOR}.
> +For example:
> +
> + at example
> +:- pred string__contains_char(string, character).
> +:- mode string__contains_char(in, in) is semidet.
> +
> +:- pragma foreign_proc("C", string__contains_char(Str::in, Ch::in),
> +        [will_not_call_mercury],
> +        "SUCCESS_INDICATOR = (strchr(Str, Ch) != NULL);").
> + at end example
> +
> + at code{SUCCESS_INDICATOR} should not be used other than as the target of
> +an assignment.
> +(For example, it may be @code{#define}d to a register, so you should not
> +try to take its address.) 
> +Procedures whose determinism indicates that that they cannot fail
> +should not access @code{SUCCESS_INDICATOR}.
> +
> +Arguments whose mode is input will have their values set by the
> +Mercury implementation on entry to the C code.  If the procedure
> +succeeds, the C code must set the values of all output arguments
> +before returning.  If the procedure fails, the C code need only
> +set @code{SUCCESS_INDICATOR} to false (zero).
> +
> + at node Using pragma foreign_decl for C
> + at subsection Using pragma foreign_decl for C
> +
> +Any macros, function prototypes, or other C declarations
> +that are used in @samp{foreign_code} or @samp{foreign_proc} 
> +pragmas must be included using a @samp{foreign_decl} declaration of the form
> +
> + at example
> +:- pragma foreign_decl("C", @var{HeaderCode}).
> + at end example
> +
> + at noindent
> + at var{HeaderCode} can be a C @samp{#include} line, for example
> +
> + at example
> +:- pragma foreign_decl("C", "#include <math.h>")
> + at end example
> +
> + at noindent
> +or
> +
> + at example
> +:- pragma foreign_decl("C", "#include ""tcl.h""").
> + at end example
> +
> + at noindent
> +or it may contain any C declarations, for example
> +
> + at example
> +:- pragma foreign_decl("C", "
> +        extern int errno;
> +        #define SIZE 200
> +        struct Employee @{
> +                char name[SIZE];
> +        @}
> +        extern int bar;
> +        extern void foo(void);
> +").
> + at end example
> +
> +Mercury automatically includes certain headers such as @code{<stdlib.h>},
> +but you should not rely on this, as the set of headers which Mercury
> +automatically includes is subject to change.
> +
> + at node Using pragma foreign_code for C
> + at subsection Using pragma foreign_code for C
> +
> +Definitions of C functions or global variables may be
> +included using a declaration of the form
> +
> + at example
> +:- pragma foreign_code("C", @var{Code}).
> + at end example
> +
> +For example,
> +
> + at example
> +:- pragma foreign_code("C", "
> +        int bar = 42;
> +        void foo(void) @{@}
> +").
> + at end example
> +
> +Such code is copied verbatim into the generated C file.
> +
> + at c ----------------------------------------------------------------------------
> +
> + at node Interfacing with C#
> + at section Interfacing with C#
> +
> + at c XXX
> +Currently undocumented, sorry.
> +
> + at menu
> +* Using pragma foreign_proc for C# 	:: Calling C# code from Mercury
> +* Using pragma foreign_decl for C# 	:: Including C# declarations in Mercury
> +* Using pragma foreign_code for C# 	:: Including C# code in Mercury
> + at end menu
> +
> + at node Using pragma foreign_proc for C#
> + at subsection Using pragma foreign_proc for C#
> +
> +Not currently supported for C#.
> + at c XXX
> +
> + at node Using pragma foreign_decl for C#
> + at subsection Using pragma foreign_decl for C#
> +
> +Not currently supported for C#.
> + at c XXX
> +
> + at node Using pragma foreign_code for C#
> + at subsection Using pragma foreign_code for C#
> +
> +Not currently supported for C#.
> + at c XXX
> +
> +
> + at c ----------------------------------------------------------------------------
> +
> + at node Interfacing with Managed C++
> + at section Interfacing with Managed C++
> +
> + at c XXX
> +Currently undocumented, sorry.
> +
> + at menu
> +* Using pragma foreign_proc for MC++::  Calling MC++ code from Mercury
> +* Using pragma foreign_decl for MC++::  Including MC++ declarations in Mercury
> +* Using pragma foreign_code for MC++::  Including MC++ code in Mercury
> + at end menu
> +
> + at node Using pragma foreign_proc for MC++
> + at subsection Using pragma foreign_proc for MC++
> +
> +Currenly undocumented, sorry.
> + at c XXX
> +
> + at node Using pragma foreign_decl for MC++
> + at subsection Using pragma foreign_decl for MC++
> +
> +Currenly undocumented, sorry.
> + at c XXX
> +
> + at node Using pragma foreign_code for MC++
> + at subsection Using pragma foreign_code for MC++
> +
> +Currenly undocumented, sorry.
> + at c XXX
> +
> + at c ----------------------------------------------------------------------------
> +
> + at node Interfacing with IL
> + at section Interfacing with IL
> +
> + at menu
> +* Using pragma foreign_proc for IL 	:: Calling IL code from Mercury
> +* Using pragma foreign_decl for IL 	:: Including IL declarations in Mercury
> +* Using pragma foreign_code for IL 	:: Including IL code in Mercury
> + at end menu
> +
> + at node Using pragma foreign_proc for IL
> + at subsection Using pragma foreign_proc for IL
> +
> +Variables can be accessed from IL by using ldloc (for input parameters) 
> +and stloc (for output parameters).
> +Do not use ret or jmp instructions or tail calls within the handwritten
> +IL code.
> +The stack must be empty at the end of the IL code.
> +
> + at example
> +:- pred add(int::in, int::in, int::out) det.
> +:- pragma foreign_proc("il", add(X::in, Y::in, Z::out), [max_stack_size(2)], "
> +	ldloc X
> +	ldloc Y
> +	add
> +	stloc Z
> +").
> + at end example
> +
> +IL code for procedures whose determinism indicates they could fail 
> +is currently not supported.
> +
> + at c XXX document how semidet works -- but get it working first.
> + at c
> + at c The IL code in a @code{pragma foreign_proc} declaration
> + at c for any procedure whose determinism indicates that it could fail
> + at c must assign a truth value to the local variable @samp{succeeded}.
> + at c For example:
> + at c
> + at c @example
> + at c :- pred same(int::in, int::in) is semidet.
> + at c :- pragma foreign_proc("il", same(X::in, Y::in), [max_stack_size(2)], "
> + at c 	ldloc X
> + at c 	ldloc Y
> + at c 	ceq
> + at c 	stloc succeeded
> + at c ").
> + at c @end example
> +
> +Arguments whose mode is input will have their values set by the
> +Mercury implementation on entry to the IL code.  If the procedure
> +succeeds, the IL code must set the values of all output arguments
> +before returning. 
> +
> + at c If the procedure fails, the IL code need only
> + at 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.
> +
> + at node Using pragma foreign_decl for IL
> + at subsection Using pragma foreign_decl for IL
> +
> +Not currently supported for IL.
> + at c XXX
> +
> + at node Using pragma foreign_code for IL
> + at subsection Using pragma foreign_code for IL
> +
> +Not currently supported for IL.
> + at c XXX
> +

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------