[m-dev.] diff: update doc for c_pointer

[Fergus Henderson]

On 08-Feb-2000, Tyson Dowd <trd at cs.mu.OZ.AU> wrote:
> On 04-Feb-2000, Zoltan Somogyi <zs at cs.mu.OZ.AU> wrote:
> > 
> > Any opinions?
> 
> A quick summary of the outcome of a discussion on this topic:
> 
> Regarding hand defined types:
> 
> 	- The traditional system of declaring "external" types is
> 	  to declare but not define a type.

... and to then go ahead and define the RTTI structures
needed for that type by hand.

This is only needed for types which need special treatment
of some kind.  It should in general not be needed simply because
the type is defined in a different language.  For that case,
the technique with c_pointer described below should be used instead.

> 	  Therefore checking for whether a type is abstract and
> 	  non-imported is equivalent to most cases of "hand defined".
> 	  This isn't true if the type is declared and defined, but the
> 	  definition is a lie (e.g. type_info/1 and bretheren).
> 
> 	- The language reference manual doesn't mention that the
> 	  implementation section of a module doesn't *have* to give the
> 	  definition of all types named in the interface.

That's because this is not something which should be documented
in the language reference manual; it's an implementation-specific
feature which users should not rely on.  Any code using this
feature will will need to be modified any time we change the
representation of our RTTI data structures, i.e. very frequently.
Such code is highly implementation dependent.  The way RTTI
is handled might be quite different for an implementation
targetting the JVM, for example.

The proper place for this feature to be documented is
in the documentation of the implementation, e.g.
somewhere in the `compiler/notes' directory
and/or in the source code for the compiler/library/runtime.

Note that if the user does declare a type and not define it,
then the current implementation will still detect the error
(presuming the type is used somewhere), just at link time
rather than compile time.

> 	- We may want to consider making it explicit when types are
> 	  external, the current system is error prone.
> 	  If it is explicit, it will be an experts only feature.
>
> 	- For the moment, we will use the traditional system, and
> 	  leave the explicit syntax as a possibility for a later date.

Actually the current system is not as error prone as we said
in our discussion, because as noted above the errors will still
be caught, just at link time rather than at compile time.

It's not just a question of "experts only"; code which defines its
own RTTI structures is inherently going to be implementation-dependent.

Personally I don't think the extra effort of defining special syntax
for this construct would be worth it, since it is only going to be
used in a few places within the implementation.  The major
argument in favour of it would be that we could then detect
types which are declared and not defined at compile time rather
than at link time.  But that is not a very strong argument, IMHO.

> Other points:
> 
> 	- Using c_pointer as
> 		:- type my_external_type ---> my_external_type(c_pointer).
> 	  is probably sufficient for most people writing external
> 	  interfaces.  We should probably document this trick (err, I
> 	  mean technique).

The technique

	:- type my_external_type == c_pointer.

is already documented in the language reference manual.
We could easily change that documentation to instead recommend
the syntax shown above.  See the diff below.
I will go ahead and commit this one.

----------

Estimated hours taken: 0.25

doc/reference_manual.texi:
	In the example use of c_pointer, use a no_tag type rather
	than an equivalence type, so that type class instance
	declarations will work properly for such a type.

Workspace: /d-drive/home/hg/fjh/mercury
Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.169
diff -u -d -r1.169 reference_manual.texi
--- doc/reference_manual.texi	2000/02/02 07:33:20	1.169
+++ doc/reference_manual.texi	2000/02/08 12:09:15
@@ -4848,7 +4849,8 @@
 :- implementation.
 
 % Our C structure is implemented as a c_pointer.
-:- type complicated_c_structure == c_pointer.
+:- type complicated_c_structure --->
+        complicated_c_structure(c_pointer).
 
 :- pragma c_header_code("
         extern struct foo *init_struct(void);
-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>  |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3        |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------