diff options
Diffstat (limited to 'doc/ref/api-data.texi')
-rw-r--r-- | doc/ref/api-data.texi | 40 |
1 files changed, 21 insertions, 19 deletions
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index 5b8db940c..5b9c5654e 100644 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -8765,22 +8765,24 @@ for ``unboxed'', as it's stored as a raw value without additional type annotations. @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 unboxed +(make-vtable "pw") ;; one scheme field +(make-vtable "pwuwuw") ;; one scheme and two unboxed fields @end example The optional @var{print} argument is a function called by @@ -8794,7 +8796,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) @@ -8828,7 +8830,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" @@ -9024,11 +9026,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 |