[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Guile-commits] 01/01: Deprecate opaque struct fields
From: |
Andy Wingo |
Subject: |
[Guile-commits] 01/01: Deprecate opaque struct fields |
Date: |
Sat, 23 Sep 2017 05:17:04 -0400 (EDT) |
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.")