[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Guile-commits] 03/07: Remove references to tail arrays in the documenta
From: |
Andy Wingo |
Subject: |
[Guile-commits] 03/07: Remove references to tail arrays in the documentation |
Date: |
Fri, 22 Sep 2017 05:49:33 -0400 (EDT) |
wingo pushed a commit to branch stable-2.2
in repository guile.
commit 53d4df80c91d0c744e86df421572f60bb9a80261
Author: Andy Wingo <address@hidden>
Date: Wed Sep 20 22:19:49 2017 +0200
Remove references to tail arrays in the documentation
* doc/ref/api-data.texi (Vtables, Structure Basics): Update to remove
references to tail arrays, in preparation for deprecation.
---
doc/ref/api-data.texi | 87 +++++++++++----------------------------------------
1 file changed, 18 insertions(+), 69 deletions(-)
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 7b10d34..7e36f74 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C) 1996, 1997, 2000-2004, 2006-2016
address@hidden Copyright (C) 1996, 1997, 2000-2004, 2006-2017
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -8757,7 +8757,6 @@ records in Guile are implemented with structures.
* Vtable Contents::
* Meta-Vtables::
* Vtable Example::
-* Tail Arrays::
@end menu
@node Vtables
@@ -8808,8 +8807,7 @@ Scheme level. This can be used for fields which should
only be used
from C code.
@end itemize
-Here are some examples. @xref{Tail Arrays}, for information on the
-legacy tail array facility.
+Here are some examples.
@example
(make-vtable "pw") ;; one writable field
@@ -8840,12 +8838,11 @@ structure.
@node Structure Basics
@subsubsection Structure Basics
-This section describes the basic procedures for working with
-structures. @code{make-struct} creates a structure, and
address@hidden and @code{struct-set!} access its fields.
+This section describes the basic procedures for working with structures.
address@hidden/no-tail} creates a structure, and @code{struct-ref}
+and @code{struct-set!} access its fields.
address@hidden {Scheme Procedure} make-struct vtable tail-size init @dots{}
address@hidden {Scheme Procedure} make-struct/no-tail vtable init @dots{}
address@hidden {Scheme Procedure} make-struct/no-tail vtable init @dots{}
Create a new structure, with layout per the given @var{vtable}
(@pxref{Vtables}).
@@ -8855,25 +8852,22 @@ put values in read-only fields. If there are fewer
@var{init}
arguments than fields then the defaults are @code{#f} for a Scheme
field (type @code{p}) or 0 for an uninterpreted field (type @code{u}).
-Structures also have the ability to allocate a variable number of
-additional cells at the end, at their tails. However, this legacy
address@hidden array} facilty is confusing and inefficient, and so we do not
-recommend it. @xref{Tail Arrays}, for more on the legacy tail array
-interface.
+The name is a bit strange, we admit. The reason for it is that Guile
+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, permission @code{o} opaque
-fields, and the count field of a tail array are all ignored for the
address@hidden arguments, ie.@: an argument is not consumed by such a
-field. An @code{s} is always set to the structure itself, an @code{o}
-is always set to @code{#f} or 0 (with the intention that C code will
-do something to it later), and the tail count is always the given
address@hidden
+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).
For example,
@example
(define v (make-vtable "prpwpw"))
-(define s (make-struct v 0 123 "abc" 456))
+(define s (make-struct/no-tail v 123 "abc" 456))
(struct-ref s 0) @result{} 123
(struct-ref s 1) @result{} "abc"
@end example
@@ -8886,6 +8880,8 @@ There are a few ways to make structures from C.
@code{scm_make_struct}
takes a list, @code{scm_c_make_struct} takes variable arguments
terminated with SCM_UNDEFINED, and @code{scm_c_make_structv} takes a
packed array.
+
+For all of these, @var{tail_size} should be zero (as a SCM value).
@end deftypefn
@deffn {Scheme Procedure} struct? obj
@@ -9197,53 +9193,6 @@ cases, the records facility is usually sufficient. But
sometimes you
need to make new kinds of data abstractions, and for that purpose,
structs are here.
address@hidden Tail Arrays
address@hidden Tail Arrays
-
-Guile's structures have a facility whereby each instance of a vtable can
-contain a variable-length tail array of values. The length of the tail
-array is stored in the structure. This facility was originally intended
-to allow C code to expose raw C structures with word-sized tail arrays
-to Scheme.
-
-However, the tail array facility is confusing and doesn't work very
-well. It is very rarely used, but it insinuates itself into all
-invocations of @code{make-struct}. For this reason the clumsily-named
address@hidden/no-tail} procedure can actually be more elegant in
-actual use, because it doesn't have a random @code{0} argument stuck in
-the middle.
-
-Tail arrays also inhibit optimization by allowing instances to affect
-their shapes. In the absence of tail arrays, all instances of a given
-vtable have the same number and kinds of fields. This uniformity can be
-exploited by the runtime and the optimizer. The presence of tail arrays
-make some of these optimizations more difficult.
-
-Finally, the tail array facility is ad-hoc and does not compose with the
-rest of Guile. If a Guile user wants an array with user-specified
-length, it's best to use a vector. It is more clear in the code, and
-the standard optimization techniques will do a good job with it.
-
-That said, we should mention some details about the interface. A vtable
-that has tail array has upper-case permission descriptors: @code{W},
address@hidden or @code{O}, correspoding to tail arrays of writable,
-read-only, or opaque elements. A tail array permission descriptor may
-only appear in the last element of a vtable layout.
-
-For exampple, @samp{pW} indicates a tail of writable Scheme-valued
-fields. The @samp{pW} field itself holds the tail size, and the tail
-fields come after it.
-
address@hidden
-(define v (make-vtable "prpW")) ;; one fixed then a tail array
-(define s (make-struct v 6 "fixed field" 'x 'y))
-(struct-ref s 0) @result{} "fixed field"
-(struct-ref s 1) @result{} 2 ;; tail size
-(struct-ref s 2) @result{} x ;; tail array ...
-(struct-ref s 3) @result{} y
-(struct-ref s 4) @result{} #f
address@hidden example
-
@node Dictionary Types
@subsection Dictionary Types
- [Guile-commits] branch stable-2.2 updated (ac0d3dc -> c7c7588), Andy Wingo, 2017/09/22
- [Guile-commits] 05/07: Remove unused code in struct.c, Andy Wingo, 2017/09/22
- [Guile-commits] 07/07: Fix up make-struct-layout and make-struct/no-tail docstrings, Andy Wingo, 2017/09/22
- [Guile-commits] 03/07: Remove references to tail arrays in the documentation,
Andy Wingo <=
- [Guile-commits] 01/07: psyntax generates calls to make-struct/no-tail, Andy Wingo, 2017/09/22
- [Guile-commits] 02/07: Use make-struct/no-tail instead of make-struct, Andy Wingo, 2017/09/22
- [Guile-commits] 06/07: Deprecate struct "self" slots, Andy Wingo, 2017/09/22
- [Guile-commits] 04/07: Deprecate make-struct, Andy Wingo, 2017/09/22