[Guile-commits] 01/01: Deprecate opaque struct fields

[Andy Wingo]

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

commit b0ecf83ef0f3dfbfce808c2cfc88ff0c8d9809f1
Author: Andy Wingo <address@hidden>
Date:   Sat Sep 23 11:14:27 2017 +0200

    Deprecate opaque struct fields
    
    * NEWS: Add entry.
    * doc/ref/api-data.texi (Vtables, Structure Basics): Remove mention of
      opaque field protection.
    * libguile/struct.c (scm_make_struct_layout, scm_make_struct_no_tail):
      Remove discussion of opaque fields.
      (set_vtable_layout_flags): Issue a deprecation warning when opaque
      fields are used.
---
 NEWS                  | 14 ++++++++++++++
 doc/ref/api-data.texi | 13 ++-----------
 libguile/struct.c     | 15 +++++++++++----
 3 files changed, 27 insertions(+), 15 deletions(-)

diff --git a/NEWS b/NEWS
index 78e3b30..fec9af3 100644
--- a/NEWS
+++ b/NEWS
@@ -67,6 +67,20 @@ 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.
 
+** Struct fields with opaque ("o") protection deprecated
+
+Struct fields are declared with a "protection", meaning read-only ('r'),
+read-write ('w'), or opaque ('o').  There is also "hidden" ('o') which
+is read-write but which isn't initialized by arguments passed to
+`make-struct/no-tail', but that's a detail.  Opaque struct fields were
+used to allocate storage in a struct that could only be accessed by C.
+This facility was very rarely used (unused in Guile itself) but now that
+we are implementing more and more in Scheme, it is completely useless.
+
+To enforce permissions on struct fields, instead layer on an abstraction
+at a higher level, in the same way that immutable record fields are
+simply those which don't have an accessor.
+
 * 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 faddc3f..e0f8be3 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -8795,9 +8795,6 @@ The second letter for each field is a permission code,
 @item
 @code{r} -- read-only, the field can be read but not written.
 @item
address@hidden -- opaque, the field can be neither read nor written at the
-Scheme level.  This can be used for fields which should only be used
-from C code.
 @end itemize
 
 Here are some examples.
@@ -8850,11 +8847,6 @@ 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.
 
-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,
 
 @example
@@ -8886,8 +8878,7 @@ Return @code{#t} if @var{obj} is a structure, or 
@code{#f} if not.
 Return the contents of field number @var{n} in @var{struct}.  The
 first field is number 0.
 
-An error is thrown if @var{n} is out of range, or if the field cannot
-be read because it's @code{o} opaque.
+An error is thrown if @var{n} is out of range.
 @end deffn
 
 @deffn {Scheme Procedure} struct-set! struct n value
@@ -8896,7 +8887,7 @@ Set field number @var{n} in @var{struct} to @var{value}.  
The first
 field is number 0.
 
 An error is thrown if @var{n} is out of range, or if the field cannot
-be written because it's @code{r} read-only or @code{o} opaque.  
+be written because it's @code{r} read-only.
 @end deffn
 
 @deffn {Scheme Procedure} struct-vtable struct
diff --git a/libguile/struct.c b/libguile/struct.c
index 5c03f4f..1363fea 100644
--- a/libguile/struct.c
+++ b/libguile/struct.c
@@ -71,8 +71,8 @@ SCM_DEFINE (scm_make_struct_layout, "make-struct-layout", 1, 
0, 0,
            "type, the second a field protection.  Allowed types are 'p' for\n"
            "GC-protected Scheme data, 'u' for unprotected binary data.  \n"
             "Allowed protections\n"
-           "are 'w' for mutable fields, 'h' for hidden fields, 'r' for 
read-only\n"
-            "fields, and 'o' for opaque fields.\n\n"
+           "are 'w' for mutable fields, 'h' for hidden fields, and\n"
+            "'r' for read-only fields.\n\n"
             "Hidden fields are writable, but they will not consume an 
initializer arg\n"
             "passed to @code{make-struct}. They are useful to add slots to a 
struct\n"
             "in a way that preserves backward-compatibility with existing 
calls to\n"
@@ -174,6 +174,13 @@ set_vtable_layout_flags (SCM vtable)
            flags &= ~SCM_VTABLE_FLAG_SIMPLE_RW;
            break;
 
+          case 'o':
+          case 'O':
+            scm_c_issue_deprecation_warning
+              ("Opaque struct fields are deprecated.  Struct field protection "
+               "should be layered on at a higher level.");
+            /* Fall through.  */
+
          default:
            flags = 0;
          }
@@ -564,8 +571,8 @@ SCM_DEFINE (scm_make_struct_no_tail, "make-struct/no-tail", 
1, 0, 1,
            "The @var{init1}, @dots{} are optional arguments describing how\n"
            "successive fields of the structure should be initialized.\n"
             "Only fields with protection 'r' or 'w' can be initialized.\n"
-            "Fields with protection 'o' can not be initialized by Scheme\n"
-            "programs.\n\n"
+            "Hidden fields (those with protection 'h') have to be manually\n"
+            "set.\n\n"
            "If fewer optional arguments than initializable fields are 
supplied,\n"
            "fields of type 'p' get default value #f while fields of type 'u' 
are\n"
            "initialized to 0.")