[m-rev.] for review: remove support for old C interface

[Ian MacLarty]

On Thu, Sep 09, 2010 at 06:19:42pm +1000, Julien Fischer wrote:
> Index: doc/reference_manual.texi
> ===================================================================
...
> + at example
> +:- pred append(string, string, string).
> +:- mode append(out, out, in) is multi.
> +
> +append(S1, S2, S3) :-
> +    S3Len = string.length(S3),
> +    append_2(0, S3Len, S1, S2, S3).
> +
> +:- pred append_2(int::in, int::in, string::::out, string::out, string::in) is multi.

Too many colons.

> +
> +append_2(NextS1Len, S3Len, S1, S2, S3) :-
> +    ( NextS1Len = S3Len ->
> +        append_3(NextS1Len, S3Len, S1, S2, S3)
> +    ;
> +        (
> +            append_3(NextS1Len, S3Len, S1, S2, S3)
> +        ;
> +            append_2(NextS1Len + 1, S3Len, S1, S2, S3)
> +        )
> +    ).
> +
> +:- pred append_3(int::inb, int::in, string::out, string::out, string::in) is det.
> +
> +:- pragma foreign_proc("C",
> +    append_3(S1Len::in, S3Len::in, S1::out, S2::out, S3::in),
> +    [will_not_call_mercury, promise_pure],
> +"
> +    S1 = allocate_string(S1Len);   /* Allocate a new string of length S1Len */
> +    memcpy(S1, S3, S1Len);
> +    S1[S1Len] = '\\0';
> +    S2 = allocate_string(S2, S3Len - S1Len);
> +    strcpy(S2, S3Len + S1Len);
> +"). +
> + at end example
>
>  @node Foreign code attributes
>  @subsection Foreign code attributes
>
>  As described above, - at c @samp{pragma import} and
>  @samp{pragma foreign_proc}
>  declarations may include a list of attributes describing properties
>  of the given foreign function or code.
> @@ -6640,8 +6678,7 @@
>  allows safe declarative debugging of code containing such calls.
>  For more information see the I/O tabling section of the Mercury user guide.
>  If the foreign procedure contains gotos or static variables then the
> - at samp{pragma no_inline} directive should also be given -(see @ref{pragma 
> c_code}).
> + at samp{pragma no_inline} directive should also be given.
>  Note that currently I/O tabling will only be done for foreign procedures
>  that take a pair of I/O state arguments.  Impure foreign procedures that
>  perform I/O will not be made idempotent, even if the tabled_for_io
> @@ -7568,6 +7605,9 @@
>  * Using pragma foreign_code for C 	 :: Including C code in Mercury
>  * Memory management for C                :: Caveats about passing dynamically
>                                              allocated memory to or from C.
> +* Linking with C object files            :: Linking with C object files and
> +                                            libraries.
> +
>  @end menu
>
>  @node Using pragma foreign_type for C
> @@ -7612,10 +7652,51 @@
>  will use @var{CForeignType} as the type for any
>  parameters whose Mercury type is @var{MercuryTypeName}.
>
> -Also see the section on using C pointers (@pxref{Using C pointers}) for
> -information on how to use the c_pointer type with the C interface.
> - at c XXX we should eventually just move that section to here,
> - at c presenting it as an alternative to pragma foreign_type.
> +The builtin Mercury type @code{c_pointer} may be used to pass C pointers
> +between C functions which are called from Mercury.  For example:
> +
> + at example
> +:- module pointer_example.
> +:- interface.
> +
> +:- type complicated_c_structure.
> +
> +% Initialise the abstract C structure that we pass around in Mercury.
> +:- pred initialise_complicated_structure(complicated_c_structure::uo) is det.
> +
> +% Perform a calculation on the C structure.
> +:- pred do_calculation(int::in, complicated_c_structure::di, +        
> complicated_c_structure::uo) is det.
> +
> +:- implementation.
> +
> +% Our C structure is implemented as a c_pointer.
> +:- type complicated_c_structure
> +    --->    complicated_c_structure(c_pointer).
> +
> +:- pragma foreign_decl("C",
> +   extern struct foo *init_struct(void);
> +   extern struct foo *perform_calculation(int, struct foo *);
> +");
> +
> +:- pragma foreign_proc("C",
> +    initialise_complicated_structure(Structure::uo),
> +    [will_not_call_mercury, may_call_mercury],
> +"
> +    Structure = init_struct();
> +").
> +
> +:- pragma foreign_proc("C",
> +    do_calculation(Value::in, Structure0::di, Structure::uo),
> +    [will_not_call_mercury, may_call_mercury],
> +"
> +    Structure = perform_calculation(Value, Structure0);
> +").
> + at end example
> +
> +We strongly recommend the use of @samp{pragma foreign_type} instead of
> + at code{c_pointer} as the use of @samp{pragma foreign_type} results in
> +more type-safe code.
>

Are you planning on getting rid of c_pointer too at some point?  If so,
do we really need an example explaining how to use it?

>  @node Using pragma foreign_export_enum for C
>  @subsubsection Using pragma foreign_export_enum for C
> @@ -7872,6 +7953,41 @@
>  methods of memory management, but more implementation experience is
>  needed before we can formulate such an interface.
>
> + at node Linking with C object files + at subsubsection Linking with C object 
> files +
> +A Mercury implementation should allow you to link with object files or
> +libraries that were produced by compiling C code.
> +The exact mechanism for linking with C object files is
> +implementation-dependent.
> +The following text describes how it is done for the University of Melbourne
> +Mercury implementation.
> +
> +To link an existing object file into your Mercury code, use the command line
> +option @samp{--link-object}.
> +For example, the following will link the object file @samp{my_function.o} from
> +the current directory when compiling the program @samp{prog}:
> +
> + at example
> +mmc --link-object my_functions.o prog
> + at end example
> +
> +The command line option @samp{--library} (or @samp{-l} for short)
> +can be used to link an existing library into your Mercury code.
> +For example, the following will link the library file @samp{libfancy_library.a},
> +or perhaps it shared version @samp{libfancy_library.so}, from the directory

s/it/the/

Looks fine otherwise.

Ian.
--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------