[Guile-commits] 06/07: Deprecate struct "self" slots

[Andy Wingo]

wingo pushed a commit to branch stable-2.2
in repository guile.

commit 04f48e94b573eaede0751110c583293cc34cd8f9
Author: Andy Wingo <address@hidden>
Date:   Fri Sep 22 11:23:00 2017 +0200

    Deprecate struct "self" slots
    
    * libguile/print.h (SCM_PRINT_STATE_LAYOUT): Use a normal slot instead
      of a self slot.
    * libguile/print.c (make_print_state): Initialize "handle" slot
      manually.
    * libguile/struct.c (issue_deprecation_warning_for_self_slots): New
      helper, called when making vtables to issue deprecation warnings for
      "self" slots.  Avoids warning for the "self" slot that's part of the
      fixed vtable slots.
      (scm_i_struct_inherit_vtable_magic): Call
      issue_deprecation_warning_for_self_slots.
    * doc/ref/api-data.texi (Vtables, Structure Basics): Remove references
      to self slots.
    * NEWS: Add entry.
---
 NEWS                  | 12 +++++++++++-
 doc/ref/api-data.texi | 16 ++++------------
 libguile/print.c      |  1 +
 libguile/print.h      |  4 ++--
 libguile/struct.c     | 20 ++++++++++++++++++++
 5 files changed, 38 insertions(+), 15 deletions(-)

diff --git a/NEWS b/NEWS
index f13f40a..78e3b30 100644
--- a/NEWS
+++ b/NEWS
@@ -26,7 +26,7 @@ If you don't care whether the URI is a relative-ref or not, 
use
 In the future `uri?' will return a true value only for URIs that specify
 a scheme.
 
-** Tail arrays deprecated
+** Struct tail arrays deprecated
 
 Guile's structures used to have a facility whereby each instance of a
 vtable can contain a variable-length tail array of values.  The length
@@ -57,6 +57,16 @@ will be removed from Guile 3.0.  Likewise, `make-struct' /
 `scm_make_struct_no_tail'.  Perhaps one day we will be able to reclaim
 the `make-struct' name!
 
+** Struct "self" slots deprecated
+
+It used to be that you could make a structure vtable that had "self"
+slots.  Instances of that vtable would have those slots initialized to
+the instance itself.  This can be useful in C code where you might have
+a pointer to the data array, and want to get the `SCM' handle for the
+structure.  However this was a little used complication without any use
+in Scheme code.  To replace it, just use "p" slots and initialize the
+slot values manually on initialization.
+
 * Bug fixes
 
 ** Enable GNU Readline 7.0's support for "bracketed paste".
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 7e36f74..faddc3f 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -8785,13 +8785,6 @@ Scheme level it's read and written as an unsigned 
integer.  ``u''
 stands for ``uninterpreted'' (it's not treated as a Scheme value), or
 ``unprotected'' (it's not marked during GC), or ``unsigned long'' (its
 size), or all of these things.
-
address@hidden
address@hidden -- a self-reference.  Such a field holds the @code{SCM} value
-of the structure itself (a circular reference).  This can be useful in
-C code where you might have a pointer to the data array, and want to
-get the Scheme @code{SCM} handle for the structure.  In Scheme code it
-has no use.
 @end itemize
 
 The second letter for each field is a permission code,
@@ -8857,11 +8850,10 @@ used to have a @code{make-struct} that took an 
additional argument;
 while we deprecate that old interface, @code{make-struct/no-tail} is the
 new name for this functionality.
 
-Type @code{s} self-reference fields and permission @code{o} opaque
-fields are ignored for the @var{init} arguments, ie.@: an argument is
-not consumed by such a field.  An @code{s} is always set to the
-structure itself and an @code{o} is always set to @code{#f} or 0 (with
-the intention that C code will do something to it later).
+Fields with permission @code{o} opaque fields are ignored for the
address@hidden arguments, ie.@: an argument is not consumed by such a field.
+An @code{o} slot is always set to @code{#f} or 0 (with the intention
+that C code will do something to it later).
 
 For example,
 
diff --git a/libguile/print.c b/libguile/print.c
index 4d57a87..24c532f 100644
--- a/libguile/print.c
+++ b/libguile/print.c
@@ -196,6 +196,7 @@ make_print_state (void)
 {
   SCM print_state = scm_make_struct_no_tail (scm_print_state_vtable, SCM_EOL);
   scm_print_state *pstate = SCM_PRINT_STATE (print_state);
+  pstate->handle = print_state;
   pstate->ref_vect = scm_c_make_vector (PSTATE_SIZE, SCM_UNDEFINED);
   pstate->ceiling = SCM_SIMPLE_VECTOR_LENGTH (pstate->ref_vect);
   pstate->highlight_objects = SCM_EOL;
diff --git a/libguile/print.h b/libguile/print.h
index 14318c0..11f533c 100644
--- a/libguile/print.h
+++ b/libguile/print.h
@@ -4,7 +4,7 @@
 #define SCM_PRINT_H
 
 /* Copyright (C) 1995, 1996, 1998, 2000, 2001, 2003, 2004, 2006, 2008,
- *   2010, 2012 Free Software Foundation, Inc.
+ *   2010, 2012, 2017 Free Software Foundation, Inc.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public License
@@ -53,7 +53,7 @@ do { \
 #define SCM_COERCE_OUTPORT(p) \
   (SCM_PORT_WITH_PS_P (p) ? SCM_PORT_WITH_PS_PORT (p) : p)
 
-#define SCM_PRINT_STATE_LAYOUT "sruwuwuwuwuwpwuwuwurprpw"
+#define SCM_PRINT_STATE_LAYOUT "pruwuwuwuwuwpwuwuwurprpw"
 typedef struct scm_print_state {
   SCM handle;                  /* Struct handle */
   int revealed;                 /* Has the state escaped to Scheme? */
diff --git a/libguile/struct.c b/libguile/struct.c
index 08451e7..3ebe890 100644
--- a/libguile/struct.c
+++ b/libguile/struct.c
@@ -30,6 +30,7 @@
 #include "libguile/_scm.h"
 #include "libguile/async.h"
 #include "libguile/chars.h"
+#include "libguile/deprecation.h"
 #include "libguile/eval.h"
 #include "libguile/alist.h"
 #include "libguile/hashtab.h"
@@ -229,6 +230,23 @@ scm_is_valid_vtable_layout (SCM layout)
   return 1;
 }
 
+static void
+issue_deprecation_warning_for_self_slots (SCM vtable)
+{
+  SCM olayout;
+  size_t idx, first_user_slot = 0;
+
+  olayout = scm_symbol_to_string (SCM_VTABLE_LAYOUT (vtable));
+  if (SCM_VTABLE_FLAG_IS_SET (vtable, SCM_VTABLE_FLAG_VTABLE))
+    first_user_slot = scm_vtable_offset_user;
+
+  for (idx = first_user_slot * 2; idx < scm_c_string_length (olayout); idx += 
2)
+    if (scm_is_eq (scm_c_string_ref (olayout, idx), SCM_MAKE_CHAR ('s')))
+      scm_c_issue_deprecation_warning
+        ("Vtables with \"self\" slots are deprecated.  Initialize these "
+         "fields manually.");
+}
+
 /* Have OBJ, a newly created vtable, inherit flags from VTABLE.  VTABLE is a
    vtable-vtable and OBJ is an instance of VTABLE.  */
 void
@@ -288,6 +306,8 @@ scm_i_struct_inherit_vtable_magic (SCM vtable, SCM obj)
       SCM_SET_VTABLE_FLAGS (obj, SCM_VTABLE_FLAG_APPLICABLE);
     }
 
+  issue_deprecation_warning_for_self_slots (obj);
+
   SCM_SET_VTABLE_FLAGS (obj, SCM_VTABLE_FLAG_VALIDATED);
 }
 #undef FUNC_NAME