summaryrefslogtreecommitdiff
path: root/doc/ref/api-data.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2017-09-23 15:16:04 +0200
committerAndy Wingo <wingo@pobox.com>2017-09-23 15:33:02 +0200
commit5870188eb4b6c4246569a1aaaf358bc8a9e6a65d (patch)
tree239d2b31275520a409576073b67a8cd952a87fc8 /doc/ref/api-data.texi
parent0f14a9e59826c1c304d1f50c741e91d99760ff43 (diff)
downloadguile-5870188eb4b6c4246569a1aaaf358bc8a9e6a65d.tar.gz
Replace "pr" struct fields with "pw" fields
* libguile/struct.h (SCM_VTABLE_BASE_LAYOUT): Layout is a "pr" field. * module/ice-9/boot-9.scm (record-type-vtable): Record vtable fields are writable. (<parameter>): "pw" fields. * module/oop/goops.scm (<class>, %compute-layout): <read-only> fields are "pw" underneath. * module/rnrs/records/procedural.scm (record-type-vtable) (record-constructor-vtable, make-record-type-descriptor): Use "pw" fields in vtables. * module/srfi/srfi-35.scm (%condition-type-vtable) (struct-layout-for-condition): "pw" fields in vtables. * test-suite/tests/goops.test: * test-suite/tests/structs.test: Use "pw" fields only. * benchmark-suite/benchmarks/structs.bm: Update for make-struct/no-tail, to use pw fields, and also to remove useless tests that the compiler would optimize away. * doc/ref/api-data.texi (Vtables): Add a note about the now-vestigial permissions character and update documentation. (Structure Basics, Meta-Vtables): Update examples. * libguile/hash.c (scm_i_struct_hash): Remove code that would handle opaque/self fields. * libguile/print.h (SCM_PRINT_STATE_LAYOUT): Use "pw" fields. * libguile/struct.c (scm_struct_init): Simplify check for hidden fields. * libguile/values.c (scm_init_values): Field is "pw".
Diffstat (limited to 'doc/ref/api-data.texi')
-rw-r--r--doc/ref/api-data.texi40
1 files changed, 21 insertions, 19 deletions
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index e0f8be324..923d0f20b 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -8787,22 +8787,24 @@ stands for ``uninterpreted'' (it's not treated as a Scheme value), or
size), or all of these things.
@end itemize
-The second letter for each field is a permission code,
-
-@itemize @bullet{}
-@item
-@code{w} -- writable, the field can be read and written.
-@item
-@code{r} -- read-only, the field can be read but not written.
-@item
-@end itemize
-
-Here are some examples.
+It used to be that the second letter for each field was a permission
+code, such as @code{w} for writable or @code{r} for read-only. However
+over time structs have become more of a raw low-level facility; access
+control is better implemented as a layer on top. After all,
+@code{struct-set!} is a cross-cutting operator that can bypass
+abstractions made by higher-level record facilities; it's not generally
+safe (in the sense of abstraction-preserving) to expose
+@code{struct-set!} to ``untrusted'' code, even if the fields happen to
+be writable. Additionally, permission checks added overhead to every
+structure access in a way that couldn't be optimized out, hampering the
+ability of structs to act as a low-level building block. For all of
+these reasons, all fields in Guile structs are now writable; attempting
+to make a read-only field will now issue a deprecation warning, and the
+field will be writable regardless.
@example
-(make-vtable "pw") ;; one writable field
-(make-vtable "prpw") ;; one read-only and one writable
-(make-vtable "pwuwuw") ;; one scheme and two uninterpreted
+(make-vtable "pw") ;; one scheme field
+(make-vtable "pwuwuw") ;; one scheme and two uninterpreted fields
@end example
The optional @var{print} argument is a function called by
@@ -8816,7 +8818,7 @@ The following print function for example shows the two fields of its
structure.
@example
-(make-vtable "prpw"
+(make-vtable "pwpw"
(lambda (struct port)
(format port "#<~a and ~a>"
(struct-ref struct 0)
@@ -8850,7 +8852,7 @@ new name for this functionality.
For example,
@example
-(define v (make-vtable "prpwpw"))
+(define v (make-vtable "pwpwpw"))
(define s (make-struct/no-tail v 123 "abc" 456))
(struct-ref s 0) @result{} 123
(struct-ref s 1) @result{} "abc"
@@ -9032,11 +9034,11 @@ vtables with additional data:
@example
scheme@@(guile-user)> (struct-ref $3 vtable-index-layout)
-$6 = pruhsruhpwphuhuhprprpw
+$6 = pwuhuhpwphuhuhpwpwpw
scheme@@(guile-user)> (struct-ref $4 vtable-index-layout)
-$7 = pruhsruhpwphuhuh
+$7 = pwuhuhpwphuhuh
scheme@@(guile-user)> standard-vtable-fields
-$8 = "pruhsruhpwphuhuh"
+$8 = "pwuhuhpwphuhuh"
scheme@@(guile-user)> (struct-ref $2 vtable-offset-user)
$9 = module
@end example