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

[Julien Fischer]

On Thu, 9 Sep 2010, Ian MacLarty wrote:

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

Fixed.

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

That's a discussion that should be had at some point, but there
are no immediate plans to get rid of it.

> If so, do we really need an example explaining how to use it?

The above example was the existing one -- I've just shifted from the old
C interface chapter.  It's worth having while the c_pointer type is
still about.

...

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

Done.

Cheers,
Julien
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------