[m-rev.] diff: fixes for trailing documentation in reference manual

[Julien Fischer]

Estimated hours taken: 0.5
Branches: main, release

Updates and fixes for the trailing documentation.

doc/reference_manual.texi:
 	Remove references to the clp(r) interface - we no longer support it.

 	Convert the trailing example code to use the new foreign language
 	interface and clean up its fromatting.

 	s/MR_current_choice_point_id()/MR_current_choicepoint_id()/

Julien.

Index: reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.357
diff -u -r1.357 reference_manual.texi
--- reference_manual.texi	5 Jul 2006 08:45:37 -0000	1.357
+++ reference_manual.texi	13 Jul 2006 07:31:09 -0000
@@ -8215,12 +8215,11 @@

  The interface used is a set of C functions (which are actually
  implemented as macros) and types.  Typically these will be
-called from C code within @samp{pragma c_code} declarations
-in Mercury code.
+called from C code within @samp{pragma foreign_proc} or
+ at samp{pramga foreign_code} declarations in Mercury code.

-For examples of the use of this interface, see the modules
- at file{extras/trailed_update/tr_array.m} and
- at file{extras/clpr/cfloat.m} in the Mercury distribution.
+For an example of the use of this interface, see the module
+ at file{extras/trailed_update/tr_array.m} in the Mercury extras distribution.

  @menu
  * Choice points::
@@ -8380,10 +8379,8 @@
  entry whenever you create a delayed goal, and putting the appropriate
  check for floundering in the @samp{MR_commit} and @samp{MR_solve} cases
  of your function.
-The Mercury distribution includes some examples of this:
-see the @samp{ML_cfloat_untrail_func()}
-function in the file @samp{extras/clpr/cfloat.m} and the
- at samp{ML_var_untrail_func()} function in the file
+The Mercury extras distribution includes an example of this:
+see the @samp{ML_var_untrail_func()} function in the file
  @samp{extras/trailed_update/var.m}.)
  If your function does detect floundering, then it should print
  an error message and then abort execution.
@@ -8508,71 +8505,69 @@
  :- type int_ref.

      % Create a new int_ref with the specified value.
+    %
  :- pred new_int_ref(int_ref::uo, int::in) is det.

-    % update_int_ref(Ref0, Ref, OldVal, NewVal):
+    % update_int_ref(Ref0, Ref, OldVal, NewVal).
      % Ref0 has value OldVal and Ref has value NewVal.
-:- pred update_int_ref(int_ref::mdi, int_ref::muo,
-        int::out, int::in) is det.
+    %
+:- pred update_int_ref(int_ref::mdi, int_ref::muo, int::out, int::in)
+    is det.

  :- implementation.

-:- type int_ref ---> int_ref(c_pointer).
+:- pragma foreign_decl("C", "

-:- pragma import(new_int_ref(uo, in),
-	"new_int_ref").
-:- pragma import(update_int_ref(mdi, muo, out, in),
-	"update_int_ref").
-
-:- pragma c_header_code("
-typedef MR_Word Mercury_IntRef;
-void new_int_ref(Mercury_IntRef *ref, MR_Integer value);
-void update_int_ref(Mercury_IntRef ref0, Mercury_IntRef *ref,
-    MR_Integer *old_value, MR_Integer new_value);
-").
-
-:- pragma c_code("
  typedef struct @{
      MR_ChoicepointId prev_choicepoint;
      MR_Integer data;
  @} C_IntRef;

-void
-new_int_ref(Mercury_IntRef *ref, MR_Integer value)
-@{
-    C_IntRef *x = malloc(sizeof(C_IntRef));
+").
+
+:- pragma foreign_type("C", int_ref, "C_IntRef *").
+
+:- pragma foreign_proc("C",
+    new_int_ref(Ref::uo, Value::in),
+    [will_not_call_mercury, promise_pure],
+"
+    C_Intref *x = malloc(sizeof(C_IntRef));
      x->prev_choicepoint = MR_current_choicepoint_id();
-    x->data = value;
-    *ref = (Mercury_IntRef) x;
-@}
-
-void
-update_int_ref(Mercury_IntRef ref0, Mercury_IntRef *ref,
-    MR_Integer *old_value, MR_Integer new_value)
-@{
-    C_IntRef *x = (C_IntRef *) ref0;
-    *old_value = x->data;
+    x->data = Value;
+    Ref = x;
+").

-    /* check whether we need to trail this update */
+:- pragma foreign_proc("C",
+    update_int_ref(Ref0::mdi, Ref::muo, OldValue::out, NewValue::in),
+    [will_not_call_mercury, promise_pure],
+"
+    C_IntRef *x = Ref0;
+    OldValue = x->data;
+
+    /* Check whether we need to trail this update. */
      if (MR_choicepoint_newer(MR_current_choicepoint_id(),
          x->prev_choicepoint))
      @{
-        /* trail both x->data and x->prev_choicepoint,
-	   since we're about to update them both*/
+        /*
+        ** Trail both x->data and x->prev_choicepoint,
+        ** since we're about to update them both.
+        */
          assert(sizeof(x->data) == sizeof(MR_Word));
          assert(sizeof(x->prev_choicepoint) == sizeof(MR_Word));
          MR_trail_current_value((MR_Word *)&x->data);
          MR_trail_current_value((MR_Word *)&x->prev_choicepoint);

-        /* update x->prev_choicepoint to indicate that
-           x->data's previous value has been trailed
-           at this choice point */
+        /*
+        ** Update x->prev_choicepoint to indicate that
+        ** x->data's previous value has been trailed
+        ** at this choice point.
+        */
          x->prev_choicepoint = MR_current_choicepoint_id();
      @}
-    x->data = new_value;
-    *ref = ref0;
-@}
+    x->data = NewValue;
+    Ref = Ref0;
  ").
+
  @end example

  @c @item @code{void MR_untrail_to(MR_TrailEntry *@var{old_trail_ptr}, MR_untrail_reason @var{reason});}

--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at csse.unimelb.edu.au
administrative address: owner-mercury-reviews at csse.unimelb.edu.au
unsubscribe: Address: mercury-reviews-request at csse.unimelb.edu.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at csse.unimelb.edu.au Message: subscribe
--------------------------------------------------------------------------