[m-rev.] for review: [CTGC] user annotated sharing

[Julien Fischer]

On Thu, 29 Jun 2006, Nancy wrote:

> > The new foreign_proc attributes need to be documented in the reference
> > manual - for the time being the documentation should be commented out
> > but it should still be added now.
>
> I've added some documentation in the reference manual. Cf. attachment.
> Does it make it all a little more clear?
>

Yes, thanks.

...

> >> +:- pred sharing_as_from_user_annotated_sharing(
> >> +    pragma_foreign_proc_attributes::in, sharing_as::out) is semidet.
> >> +
> >> +sharing_as_from_user_annotated_sharing(Attributes, UserSharingAs) :-
> >> +    UserSharing = user_annotated_sharing(Attributes),
> >> +    UserSharing = user_sharing(SharingDomain, _MaybeTypes),
> >> +    % Accept only the value "bottom" and "real" for the structure sharing.
> >> +    % If the user has annotated the sharing with unknown sharing, we might
> >> +    % try to predict bottom anyway.
> >> +    some [!SharingAs] (
> >> +        (
> >> +            SharingDomain = structure_sharing_bottom,
> >> +            !:SharingAs = sharing_as_bottom
> >> +        ;
> >> +            SharingDomain = structure_sharing_real(_SharingPairs),
> >> +            !:SharingAs = from_structure_sharing_domain(SharingDomain)
> >> +
> >> +            % XXX
> >> +            % I have the feeling that renaming should not be needed at this
> >> +            % place anymore, assuming that every foreign_proc call is
> >
> > That sentence is incomplete.
>
> It was saying:
>
> % I have the feeling that renaming should not be needed at this
> % place anymore, assuming that every foreign_proc call is
> % correctly handled at the add_pragma stage?
>
> The thing is, I feel a little insecure with all the renaming in the
> different stages...
>
> * when parsing, the sharing information is in terms of the vars and
> typevars that are part of the same foreign_proc declaration.

Yes.

> * this is renamed when adding the pragma to the HLDS, so that everything
> becomes in terms of the vars/typevars used in the pred_info for that
> foreign_proc...

No, at least for the vars.  They can't be renamed because they might be used
within the foreign code.  To add a foreign clause for a predicate we insert
a some extra unifications between the head of the predicate and the
foreign_proc goal.  (For details see clauses_info_add_pragma_foreign_proc
in add_pragma.m.)

As for the type variables, I haven't checked but I can't think why they
would need to be renamed.

> * during the actual sharing analysis, we need to handle foreign_proc
> goals... and I have the feeling that the sharing recorded in its
> attributes will definitely be in terms of the arguments of that
> foreign_proc. But I am really unsure of this... okay, I could do
> renaming anyway, but it would be good to know how things work there..

See above - as I understand it no renaming should be necessary (in fact
it would probably be incorrect) provided that the sharing analysis handles
foreign_proc goals correctly.

...

Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.355
diff -u -d -r1.355 reference_manual.texi
--- doc/reference_manual.texi	14 Jun 2006 08:14:50 -0000	1.355
+++ doc/reference_manual.texi	29 Jun 2006 08:20:21 -0000

...


@@ -6327,6 +6327,56 @@
 procedures that @samp{may_call_mercury}, in case none is specified, is
 @samp{may_call_mm_tabled}.

+ at c @item @samp{no_sharing/unknown_sharing/sharing(MaybeTypes, SharingList)}
+ at c This attribute declares whether or not the foreign procedure creates any
+ at c structure sharing @ref{Structure sharing analysis} between the output
+ at c arguments
+ at c of the foreign procedure and its input arguments.

I suggest:

	This attribute declares whether or not a foreign procedure creates any
	structure sharing @ref{...} between its input and output arguments.

+ at c Specifying that a foreign
+ at c procedure generates no sharing (attribute @samp{no_sharing}) is a promise
+ at c to the compiler that the procedure does not create any sharing
+ at c between its arguments. The attribute @samp{unknown_sharing} specifies
+ at c that the
+ at c procedure may create any possible sharing between the arguments.
+ at c Finally, using
+ at c @samp{sharing(MaybeTypes, SharingList)} it is possible to specify a list of
+ at c sharing arguments, declaring that the foreign procedure creates at most
+ at c the specified sharing between the arguments. @samp{MaybeTypes} takes
+ at c the values
+ at c @samp{no/yes(Types)}, where @samp{Types} correspond to the types used in the

s/correspond/corresponds/

+ at c predicate declaration of this foreign procedure.

s/predicate/predicate or function/
s/of/for/

+ at c @samp{SharingList} consists of a list
+ at c @samp{[SharingPairA, SharingPairB, ...]}, where each sharing pair
+ at c is represented by a pair @samp{cel(Vari, Seli) - cel(Varj, Selj)}.
+ at c @samp{Vari, Varj} must be variables that are part of the mode declaration
+ at c of the @samp{foreign_proc} definition. @samp{Seli, Selj} select
+ at c the subterms of the given arguments that actually share. Each selector
+ at c @samp{Seli} is written as a list of types @samp{[Type1, Type2, ...]}
+ at c representing a path in the term structure of the given argument. An
+ at c empty list designates the complete term to which the argument corresponds.
+ at c The types can make use of type variables as long as @samp{MaybeTypes} is
+ at c set to @samp{yes(Types)}, and the type variables occur in any of the types
+ at c used in @samp{Types}.

I'm not entirely convinced by the syntax of the sharing attribute ... but
since I can't think of an alternative I'll just shut-up :-)

+ at c @example
+ at c :- pred array.init_2(int::in, T::in, array(T)::array_uo) is det.
+ at c
+ at c :- pragma foreign_proc("C",
+    @c array.init_2(Size::in, Item::in, Array::array_uo),
+    @c [will_not_call_mercury, promise_pure, thread_safe, will_not_modify_trail,
+    @c sharing(yes(int, T, array(T)), [cel(Item,[]) - cel(Array,[T])])],
+ at c "
+    @c ML_alloc_array(Array, Size + 1, MR_PROC_LABEL);
+    @c ML_init_array(Array, Size, Item);
+ at c ").
+ at c @end example
+ at c
+ at c This sharing declaration promises that a call
+ at c @code{init_2(Size, Item, Array)}, with types @code{int, T, array(T)}
+ at c may create sharing between any
+ at c subterms of type @code{T} of the resulting array @code{Array} and the
+ at c term @code{Item}. Reformulated: the elements of @code{Array} may refer
+ at c to the same memory locations as @code{Item}.
+
 @end table

 @c -----------------------------------------------------------------------
@@ -9571,6 +9621,18 @@
 @c Note that neither the @samp{reserve_tag} pragma nor the @samp{--reserve-tag}
 @c compiler option will have any useful effect if the @samp{--high-level-data}
 @c option is used (e.g. for the .NET or Java back-ends).
+
+ at c XXX TO DO!
+ at c @node Structure sharing analysis
+ at c @section Structure sharing analysis
+ at c
+ at c The compiler includes a structure sharing analysis system.
+
+ at c XXX TO DO!
+ at c @node Compile-time garbage collection
+ at c @section Compile-time garbage collection
+ at c
+ at c The compiler includes a compile-time garbage collection system (CTGC).

I think that there should be just one section, Compile-time garbage
collection, and the description of sharing should be a sub-section of that.

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