diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ref/ChangeLog | 33 | ||||
-rw-r--r-- | doc/ref/api-compound.texi | 547 | ||||
-rw-r--r-- | doc/ref/api-io.texi | 29 | ||||
-rw-r--r-- | doc/ref/posix.texi | 107 | ||||
-rw-r--r-- | doc/ref/slib.texi | 40 |
5 files changed, 441 insertions, 315 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index 85020e993..e911cfb0d 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,8 +1,36 @@ +2007-03-08 Kevin Ryde <user42@zip.com.au> + + * api-compound.texi (Structures): Revise and expand variously, add + make-vtable. + + * api-io.texi: Add various @cindex entries. + + * slib.texi (SLIB): Shorten the bit about core funcs overridden. + Don't want to duplicate the SLIB specs, and the set of modified bits + is likely to change over time and don't want to have to keep up with + that. + +2007-02-22 Kevin Ryde <user42@zip.com.au> + + * posix.texi (Signals): Merge sleep and usleep, note usleep not + actually microsecond accurate, remove warning usleep not always + available (guile has own code for it now, it's not the system call). + Cross reference scm_std_sleep / scm_std_usleep. + + * posix.texi (Signals): Merge getitimer and setitimer, describe what + each timer does, use @defvar to get them indexed, caution may not + actually be microsecond accurate. + 2007-02-20 Neil Jerram <neil@ossau.uklinux.net> * Makefile.am (EXTRA_DIST): Add lib-version.texi to the distribution. +2007-02-16 Kevin Ryde <user42@zip.com.au> + + * api-compound.texi (Records): In make-record-type, describe optional + print function argument. + 2007-01-31 Ludovic Courtès <ludovic.courtes@laas.fr> * api-data.texi (Conversion): Made cross refs point to `Number @@ -18,6 +46,11 @@ * srfi-modules.texi (SRFI-19 String to date): Mention the internationalization of `string->date'. +2007-01-25 Kevin Ryde <user42@zip.com.au> + + * posix.texi (Signals): Note signal handlers run via system async and + can hence be delayed quite a while. Struck by William Xu. + 2007-01-19 Han-Wen Nienhuys <hanwen@lilypond.org> * api-options.texi (Evaluator trap options): document diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi index 44410d158..c551c4d10 100644 --- a/doc/ref/api-compound.texi +++ b/doc/ref/api-compound.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -2611,14 +2611,22 @@ Note that @code{record?} may be true of any Scheme value; there is no promise that records are disjoint with other Scheme types. @end deffn -@deffn {Scheme Procedure} make-record-type type-name field-names -Return a @dfn{record-type descriptor}, a value representing a new data -type disjoint from all others. The @var{type-name} argument must be a -string, but is only used for debugging purposes (such as the printed -representation of a record of the new type). The @var{field-names} -argument is a list of symbols naming the @dfn{fields} of a record of the -new type. It is an error if the list contains any duplicates. It is -unspecified how record-type descriptors are represented. +@deffn {Scheme Procedure} make-record-type type-name field-names [print] +Create and return a new @dfn{record-type descriptor}. + +@var{type-name} is a string naming the type. Currently it's only used +in the printed representation of records, and in diagnostics. +@var{field-names} is a list of symbols naming the fields of a record +of the type. Duplicates are not allowed among these symbols. + +@example +(make-record-type "employee" '(name age salary)) +@end example + +The optional @var{print} argument is a function used by +@code{display}, @code{write}, etc, for printing a record of the new +type. It's called as @code{(@var{print} record port)} and should look +at @var{record} and write to @var{port}. @end deffn @deffn {Scheme Procedure} record-constructor rtd [field-names] @@ -2692,296 +2700,369 @@ created the type represented by @var{rtd}. @subsection Structures @tpindex Structures -[FIXME: this is pasted in from Tom Lord's original guile.texi and should -be reviewed] - -A @dfn{structure type} is a first class user-defined data type. A -@dfn{structure} is an instance of a structure type. A structure type is -itself a structure. +A @dfn{structure} is a first class data type which holds Scheme values +or C words in fields numbered 0 upwards. A @dfn{vtable} represents a +structure type, giving field types and permissions, and an optional +print function for @code{write} etc. -Structures are less abstract and more general than traditional records. -In fact, in Guile Scheme, records are implemented using structures. +Structures are lower level than records (@pxref{Records}) but have +some extra features. The vtable system allows sets of types be +constructed, with class data. The uninterpreted words can +inter-operate with C code, allowing arbitrary pointers or other values +to be stored along side usual Scheme @code{SCM} values. @menu -* Structure Concepts:: The structure of Structures -* Structure Layout:: Defining the layout of structure types -* Structure Basics:: make-, -ref and -set! procedures for structs -* Vtables:: Accessing type-specific data +* Vtables:: +* Structure Basics:: +* Vtable Contents:: +* Vtable Vtables:: @end menu -@node Structure Concepts -@subsubsection Structure Concepts +@node Vtables, Structure Basics, Structures, Structures +@subsubsection Vtables -A structure object consists of a handle, structure data, and a vtable. -The handle is a Scheme value which points to both the vtable and the -structure's data. Structure data is a dynamically allocated region of -memory, private to the structure, divided up into typed fields. A -vtable is another structure used to hold type-specific data. Multiple -structures can share a common vtable. +A vtable is a structure type, specifying its layout, and other +information. A vtable is actually itself a structure, but there's no +need to worray about that initially (@pxref{Vtable Contents}.) -When applied to structures, the @code{equal?} predicate -(@pxref{Equality}) returns @code{#t} if the two structures share a -common vtable @emph{and} all their fields satisfy @code{equal?}. +@deffn {Scheme Procedure} make-vtable fields [print] +Create a new vtable. -Three concepts are key to understanding structures. +@var{fields} is a string describing the fields in the structures to be +created. Each field is represented by two characters, a type letter +and a permissions letter, for example @code{"pw"}. The types are as +follows. @itemize @bullet{} -@item @dfn{layout specifications} - -Layout specifications determine how memory allocated to structures is -divided up into fields. Programmers must write a layout specification -whenever a new type of structure is defined. - -@item @dfn{structural accessors} - -Structure access is by field number. There is only one set of -accessors common to all structure objects. +@item +@code{p} -- a Scheme value. ``p'' stands for ``protected'' meaning +it's protected against garbage collection. -@item @dfn{vtables} +@item +@code{u} -- an arbitrary word of data (an @code{scm_t_bits}). At the +Scheme level it's read and written as an unsigned integer. ``u'' +stands for ``uninterpreted'' (it's not treated as a Scheme value), or +``unprotected'' (it's not marked during GC), or ``unsigned long'' (its +size), or all of these things. -Vtables, themselves structures, are first class representations of -disjoint sub-types of structures in general. In most cases, when a -new structure is created, programmers must specify a vtable for the -new structure. Each vtable has a field describing the layout of its -instances. Vtables can have additional, user-defined fields as well. +@item +@code{s} -- a self-reference. Such a field holds the @code{SCM} value +of the structure itself (a circular reference). This can be useful in +C code where you might have a pointer to the data array, and want to +get the Scheme @code{SCM} handle for the structure. In Scheme code it +has no use. @end itemize - - -@node Structure Layout -@subsubsection Structure Layout - -When a structure is created, a region of memory is allocated to hold its -state. The @dfn{layout} of the structure's type determines how that -memory is divided into fields. - -Each field has a specified type. There are only three types allowed, each -corresponding to a one letter code. The allowed types are: +The second letter for each field is a permission code, @itemize @bullet{} -@item 'u' -- unprotected - -The field holds binary data that is not GC protected. - -@item 'p' -- protected - -The field holds a Scheme value and is GC protected. - -@item 's' -- self - -The field holds a Scheme value and is GC protected. When a structure is -created with this type of field, the field is initialized to refer to -the structure's own handle. This kind of field is mainly useful when -mixing Scheme and C code in which the C code may need to compute a -structure's handle given only the address of its malloc'd data. +@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 +@code{o} -- 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. +@item +@code{W},@code{R},@code{O} -- a tail array, with permissions for the +array fields as per @code{w},@code{r},@code{o}. @end itemize +A tail array is further fields at the end of a structure. The last +field in the layout string might be for instance @samp{pW} to have a +tail of writable Scheme-valued fields. The @samp{pW} field itself +holds the tail size, and the tail fields come after it. -Each field also has an associated access protection. There are only -three kinds of protection, each corresponding to a one letter code. -The allowed protections are: +Here are some examples. -@itemize @bullet{} -@item 'w' -- writable +@example +(make-vtable "pw") ;; one writable field +(make-vtable "prpw") ;; one read-only and one writable +(make-vtable "pwuwuw") ;; one scheme and two uninterpreted -The field can be read and written. +(make-vtable "prpW") ;; one fixed then a tail array +@end example -@item 'r' -- readable +The optional @var{print} argument is a function called by +@code{display} and @code{write} (etc) to give a printed representation +of a structure created from this vtable. It's called +@code{(@var{print} struct port)} and should look at @var{struct} and +write to @var{port}. The default print merely gives a form like +@samp{#<struct ADDR:ADDR>} with a pair of machine addresses. -The field can be read, but not written. +The following print function for example shows the two fields of its +structure. -@item 'o' -- opaque +@example +(make-vtable "prpw" + (lambda (struct port) + (display "#<") + (display (struct-ref 0)) + (display " and ") + (display (struct-ref 1)) + (display ">"))) +@end example +@end deffn -The field can be neither read nor written. This kind -of protection is for fields useful only to built-in routines. -@end itemize -A layout specification is described by stringing together pairs -of letters: one to specify a field type and one to specify a field -protection. For example, a traditional cons pair type object could -be described as: +@node Structure Basics, Vtable Contents, Vtables, Structures +@subsubsection Structure Basics -@example -; cons pairs have two writable fields of Scheme data -"pwpw" -@end example +This section describes the basic procedures for working with +structures. @code{make-struct} creates a structure, and +@code{struct-ref} and @code{struct-set!} access write fields. + +@deffn {Scheme Procedure} make-struct vtable tail-size [init...] +@deffnx {C Function} scm_make_struct (vtable, tail_size, init_list) +Create a new structure, with layout per the given @var{vtable} +(@pxref{Vtables}). + +@var{tail-size} is the size of the tail array if @var{vtable} +specifies a tail array. @var{tail-size} should be 0 when @var{vtable} +doesn't specify a tail array. + +The optional @var{init}@dots{} arguments are initial values for the +fields of the structure (and the tail array). This is the only way to +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}). + +Type @code{s} self-reference fields, permission @code{o} opaque +fields, and the count field of a tail array are all 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, 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 +@var{tail-size}. -A pair object in which the first field is held constant could be: +For example, @example -"prpw" +(define v (make-vtable "prpwpw")) +(define s (make-struct v 0 123 "abc" 456)) +(struct-ref s 0) @result{} 123 +(struct-ref s 1) @result{} "abc" @end example -Binary fields, (fields of type "u"), hold one @dfn{word} each. The -size of a word is a machine dependent value defined to be equal to the -value of the C expression: @code{sizeof (long)}. - -The last field of a structure layout may specify a tail array. -A tail array is indicated by capitalizing the field's protection -code ('W', 'R' or 'O'). A tail-array field is replaced by -a read-only binary data field containing an array size. The array -size is determined at the time the structure is created. It is followed -by a corresponding number of fields of the type specified for the -tail array. For example, a conventional Scheme vector can be -described as: - @example -; A vector is an arbitrary number of writable fields holding Scheme -; values: -"pW" +(define v (make-vtable "prpW")) +(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 @end example +@end deffn -In the above example, field 0 contains the size of the vector and -fields beginning at 1 contain the vector elements. +@deffn {Scheme Procedure} struct? obj +@deffnx {C Function} scm_struct_p (obj) +Return @code{#t} if @var{obj} is a structure, or @code{#f} if not. +@end deffn -A kind of tagged vector (a constant tag followed by conventional -vector elements) might be: +@deffn {Scheme Procedure} struct-ref struct n +@deffnx {C Function} scm_struct_ref (struct, n) +Return the contents of field number @var{n} in @var{struct}. The +first field is number 0. -@example -"prpW" -@end example +An error is thrown if @var{n} is out of range, or if the field cannot +be read because it's @code{o} opaque. +@end deffn +@deffn {Scheme Procedure} struct-set! struct n value +@deffnx {C Function} scm_struct_set_x (struct, n, value) +Set field number @var{n} in @var{struct} to @var{value}. The first +field is number 0. -Structure layouts are represented by specially interned symbols whose -name is a string of type and protection codes. To create a new -structure layout, use this procedure: +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. +@end deffn -@deffn {Scheme Procedure} make-struct-layout fields -@deffnx {C Function} scm_make_struct_layout (fields) -Return a new structure layout object. +@deffn {Scheme Procedure} struct-vtable struct +@deffnx {C Function} scm_struct_vtable (struct) +Return the vtable used by @var{struct}. -@var{fields} must be a string made up of pairs of characters -strung together. The first character of each pair describes a field -type, the second a field protection. Allowed types are 'p' for -GC-protected Scheme data, 'u' for unprotected binary data, and 's' for -a field that points to the structure itself. Allowed protections -are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque -fields. The last field protection specification may be capitalized to -indicate that the field is a tail-array. +This can be used to examine the layout of an unknown structure, see +@ref{Vtable Contents}. @end deffn +@node Vtable Contents, Vtable Vtables, Structure Basics, Structures +@subsubsection Vtable Contents -@node Structure Basics -@subsubsection Structure Basics +A vtable is itself a structure, with particular fields that hold +information about the structures to be created. These include the +fields of those structures, and the print function for them. The +variables below allow access to those fields. -This section describes the basic procedures for creating and accessing -structures. +@deffn {Scheme Procedure} struct-vtable? obj +@deffnx {C Function} scm_struct_vtable_p (obj) +Return @code{#t} if @var{obj} is a vtable structure. -@deffn {Scheme Procedure} make-struct vtable tail_array_size . init -@deffnx {C Function} scm_make_struct (vtable, tail_array_size, init) -Create a new structure. +Note that because vtables are simply structures with a particular +layout, @code{struct-vtable?} can potentially return true on an +application structure which merely happens to look like a vtable. +@end deffn -@var{type} must be a vtable structure (@pxref{Vtables}). +@defvr {Scheme Variable} vtable-index-layout +@defvrx {C Macro} scm_vtable_index_layout +The field number of the layout specification in a vtable. The layout +specification is a symbol like @code{pwpw} formed from the fields +string passed to @code{make-vtable}, or created by +@code{make-struct-layout} (@pxref{Vtable Vtables}). -@var{tail-elts} must be a non-negative integer. If the layout -specification indicated by @var{type} includes a tail-array, -this is the number of elements allocated to that array. +@example +(define v (make-vtable "pwpw" 0)) +(struct-ref v vtable-index-layout) @result{} pwpw +@end example -The @var{init1}, @dots{} are optional arguments describing how -successive fields of the structure should be initialized. Only fields -with protection 'r' or 'w' can be initialized, except for fields of -type 's', which are automatically initialized to point to the new -structure itself; fields with protection 'o' can not be initialized by -Scheme programs. +This field is read-only, since the layout of structures using a vtable +cannot be changed. +@end defvr -If fewer optional arguments than initializable fields are supplied, -fields of type 'p' get default value #f while fields of type 'u' are -initialized to 0. +@defvr {Scheme Variable} vtable-index-vtable +@defvrx {C Macro} scm_vtable_index_vtable +A self-reference to the vtable, ie.@: a type @code{s} field. This is +used by C code within Guile and has no use at the Scheme level. +@end defvr -Structs are currently the basic representation for record-like data -structures in Guile. The plan is to eventually replace them with a -new representation which will at the same time be easier to use and -more powerful. +@defvr {Scheme Variable} vtable-index-printer +@defvrx {C Macro} scm_vtable_index_printer +The field number of the printer function. This field contains @code{#f} +if the default print function should be used. -For more information, see the documentation for @code{make-vtable-vtable}. -@end deffn +@example +(define (my-print-func struct port) + ...) +(define v (make-vtable "pwpw" my-print-func)) +(struct-ref v vtable-index-printer) @result{} my-print-func +@end example -@deffn {Scheme Procedure} struct? x -@deffnx {C Function} scm_struct_p (x) -Return @code{#t} iff @var{x} is a structure object, else -@code{#f}. -@end deffn +This field is writable, allowing the print function to be changed +dynamically. +@end defvr +@deffn {Scheme Procedure} struct-vtable-name vtable +@deffnx {Scheme Procedure} set-struct-vtable-name! vtable name +@deffnx {C Function} scm_struct_vtable_name (vtable) +@deffnx {C Function} scm_set_struct_vtable_name_x (vtable, name) +Get or set the name of @var{vtable}. @var{name} is a symbol and is +used in the default print function when printing structures created +from @var{vtable}. -@deffn {Scheme Procedure} struct-ref handle pos -@deffnx {Scheme Procedure} struct-set! struct n value -@deffnx {C Function} scm_struct_ref (handle, pos) -@deffnx {C Function} scm_struct_set_x (struct, n, value) -Access (or modify) the @var{n}th field of @var{struct}. +@example +(define v (make-vtable "pw")) +(set-struct-vtable-name! v 'my-name) -If the field is of type 'p', then it can be set to an arbitrary value. +(define s (make-struct v 0)) +(display s) @print{} #<my-name b7ab3ae0:b7ab3730> +@end example +@end deffn -If the field is of type 'u', then it can only be set to a non-negative -integer value small enough to fit in one machine word. +@deffn {Scheme Procedure} struct-vtable-tag vtable +@deffnx {C Function} scm_struct_vtable_tag (vtable) +Return the tag of the given @var{vtable}. +@c +@c FIXME: what can be said about what this means? +@c @end deffn +@node Vtable Vtables, , Vtable Contents, Structures +@subsubsection Vtable Vtables -@node Vtables -@subsubsection Vtables +As noted above, a vtable is a structure and that structure is itself +described by a vtable. Such a ``vtable of a vtable'' can be created +with @code{make-vtable-vtable} below. This can be used to build sets +of related vtables, possibly with extra application fields. -Vtables are structures that are used to represent structure types. Each -vtable contains a layout specification in field -@code{vtable-index-layout} -- instances of the type are laid out -according to that specification. Vtables contain additional fields -which are used only internally to libguile. The variable -@code{vtable-offset-user} is bound to a field number. Vtable fields -at that position or greater are user definable. +This second level of vtable can be a little confusing. The ball +example below is a typical use, adding a ``class data'' field to the +vtables, from which instance structures are created. The current +implementation of Guile's own records (@pxref{Records}) does something +similar, a record type descriptor is a vtable with room to hold the +field names of the records to be created from it. -@deffn {Scheme Procedure} struct-vtable handle -@deffnx {C Function} scm_struct_vtable (handle) -Return the vtable structure that describes the type of @var{struct}. -@end deffn +@deffn {Scheme Procedure} make-vtable-vtable user-fields tail-size [print] +@deffnx {C Function} scm_make_vtable_vtable (user_fields, tail_size, print_and_init_list) +Create a ``vtable-vtable'' which can be used to create vtables. This +vtable-vtable is also a vtable, and is self-describing, meaning its +vtable is itself. The following is a simple usage. -@deffn {Scheme Procedure} struct-vtable? x -@deffnx {C Function} scm_struct_vtable_p (x) -Return @code{#t} iff @var{x} is a vtable structure. -@end deffn +@example +(define vt-vt (make-vtable-vtable "" 0)) +(define vt (make-struct vt-vt 0 + (make-struct-layout "pwpw")) +(define s (make-struct vt 0 123 456)) -If you have a vtable structure, @code{V}, you can create an instance of -the type it describes by using @code{(make-struct V ...)}. But where -does @code{V} itself come from? One possibility is that @code{V} is an -instance of a user-defined vtable type, @code{V'}, so that @code{V} is -created by using @code{(make-struct V' ...)}. Another possibility is -that @code{V} is an instance of the type it itself describes. Vtable -structures of the second sort are created by this procedure: +(struct-ref s 0) @result{} 123 +@end example -@deffn {Scheme Procedure} make-vtable-vtable user_fields tail_array_size . init -@deffnx {C Function} scm_make_vtable_vtable (user_fields, tail_array_size, init) -Return a new, self-describing vtable structure. +@code{make-struct} is used to create a vtable from the vtable-vtable. +The first initializer is a layout object (field +@code{vtable-index-layout}), usually obtained from +@code{make-struct-layout} (below). An optional second initializer is +a printer function (field @code{vtable-index-printer}), used as +described under @code{make-vtable} (@pxref{Vtables}). -@var{user-fields} is a string describing user defined fields of the -vtable beginning at index @code{vtable-offset-user} -(see @code{make-struct-layout}). +@sp 1 +@var{user-fields} is a layout string giving extra fields to have in +the vtables. A vtable starts with some base fields as per @ref{Vtable +Contents}, and @var{user-fields} is appended. The @var{user-fields} +start at field number @code{vtable-offset-user} (below), and exist in +both the vtable-vtable and in the vtables created from it. Such +fields provide space for ``class data''. For example, -@var{tail-size} specifies the size of the tail-array (if any) of -this vtable. +@example +(define vt-of-vt (make-vtable-vtable "pw" 0)) +(define vt (make-struct vt-of-vt 0)) +(struct-set! vt vtable-offset-user "my class data") +@end example + +@var{tail-size} is the size of the tail array in the vtable-vtable +itself, if @var{user-fields} specifies a tail array. This should be 0 +if nothing extra is required or the format has no tail array. The +tail array field such as @samp{pW} holds the tail array size, as +usual, and is followed by the extra space. -@var{init1}, @dots{} are the optional initializers for the fields of -the vtable. +@example +(define vt-vt (make-vtable-vtable "pW" 20)) +(define my-vt-tail-start (1+ vtable-offset-user)) +(struct-set! vt-vt (+ 3 my-vt-tail-start) "data in tail") +@end example -Vtables have one initializable system field---the struct printer. -This field comes before the user fields in the initializers passed -to @code{make-vtable-vtable} and @code{make-struct}, and thus works as -a third optional argument to @code{make-vtable-vtable} and a fourth to -@code{make-struct} when creating vtables: +The optional @var{print} argument is used by @code{display} and +@code{write} (etc) to print the vtable-vtable and any vtables created +from it. It's called as @code{(@var{print} vtable port)} and should +look at @var{vtable} and write to @var{port}. The default is the +usual structure print function, which just gives machine addresses. +@end deffn -If the value is a procedure, it will be called instead of the standard -printer whenever a struct described by this vtable is printed. -The procedure will be called with arguments STRUCT and PORT. +@deffn {Scheme Procedure} make-struct-layout fields +@deffnx {C Function} scm_make_struct_layout (fields) +Return a structure layout symbol, from a @var{fields} string. +@var{fields} is as described under @code{make-vtable} +(@pxref{Vtables}). An invalid @var{fields} string is an error. -The structure of a struct is described by a vtable, so the vtable is -in essence the type of the struct. The vtable is itself a struct with -a vtable. This could go on forever if it weren't for the -vtable-vtables which are self-describing vtables, and thus terminate -the chain. +@example +(make-struct-layout "prpW") @result{} prpW +(make-struct-layout "blah") @result{} ERROR +@end example +@end deffn -There are several potential ways of using structs, but the standard -one is to use three kinds of structs, together building up a type -sub-system: one vtable-vtable working as the root and one or several -"types", each with a set of "instances". (The vtable-vtable should be -compared to the class <class> which is the class of itself.) +@defvr {Scheme Variable} vtable-offset-user +@defvrx {C Macro} scm_vtable_offset_user +The first field in a vtable which is available for application use. +Such fields only exist when specified by @var{user-fields} in +@code{make-vtable-vtable} above. +@end defvr + +@sp 1 +Here's an extended vtable-vtable example, creating classes of +``balls''. Each class has a ``colour'', which is fixed. Instances of +those classes are created, and such each such ball has an ``owner'', +which can be changed. @lisp (define ball-root (make-vtable-vtable "pr" 0)) @@ -3005,22 +3086,6 @@ compared to the class <class> which is the class of itself.) (define ball (make-ball green 'Nisse)) ball @result{} #<a green ball owned by Nisse> @end lisp -@end deffn - -@deffn {Scheme Procedure} struct-vtable-name vtable -@deffnx {C Function} scm_struct_vtable_name (vtable) -Return the name of the vtable @var{vtable}. -@end deffn - -@deffn {Scheme Procedure} set-struct-vtable-name! vtable name -@deffnx {C Function} scm_set_struct_vtable_name_x (vtable, name) -Set the name of the vtable @var{vtable} to @var{name}. -@end deffn - -@deffn {Scheme Procedure} struct-vtable-tag handle -@deffnx {C Function} scm_struct_vtable_tag (handle) -Return the vtable tag of the structure @var{handle}. -@end deffn @node Dictionary Types diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi index 0d30c4d2a..f69d07ede 100644 --- a/doc/ref/api-io.texi +++ b/doc/ref/api-io.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -24,6 +24,7 @@ @node Ports @subsection Ports +@cindex Port Sequential input/output in Scheme is represented by operations on a @dfn{port}. This chapter explains the operations that Guile provides @@ -94,10 +95,12 @@ Equivalent to @code{(or (input-port? @var{x}) (output-port? @node Reading @subsection Reading +@cindex Reading [Generic procedures for reading from ports.] @rnindex eof-object? +@cindex End of file object @deffn {Scheme Procedure} eof-object? x @deffnx {C Function} scm_eof_object_p (x) Return @code{#t} if @var{x} is an end-of-file object; otherwise @@ -217,6 +220,7 @@ Set the current column or line number of @var{port}. @node Writing @subsection Writing +@cindex Writing [Generic procedures for writing to ports.] @@ -320,6 +324,8 @@ all open output ports. The return value is unspecified. @node Closing @subsection Closing +@cindex Closing ports +@cindex Port, close @deffn {Scheme Procedure} close-port port @deffnx {C Function} scm_close_port (port) @@ -354,6 +360,8 @@ open. @node Random Access @subsection Random Access +@cindex Random access, ports +@cindex Port, random access @deffn {Scheme Procedure} seek fd_port offset whence @deffnx {C Function} scm_seek (fd_port, offset, whence) @@ -410,6 +418,8 @@ the current size, but this is not mandatory in the POSIX standard. @node Line/Delimited @subsection Line Oriented and Delimited Text +@cindex Line input/output +@cindex Port, line input/output The delimited-I/O module can be accessed with: @@ -520,6 +530,8 @@ delimiter may be either a newline or the @var{eof-object}; if @node Block Reading and Writing @subsection Block reading and writing +@cindex Block read/write +@cindex Port, block read/write The Block-string-I/O module can be accessed with: @@ -618,6 +630,8 @@ return 0 immediately if the request size is 0 bytes. @node Default Ports @subsection Default Ports for Input, Output and Errors +@cindex Default ports +@cindex Port, default @rnindex current-input-port @deffn {Scheme Procedure} current-input-port @@ -693,6 +707,8 @@ initialized with the @var{port} argument. @node Port Types @subsection Types of Port +@cindex Types of ports +@cindex Port, types [Types of port; how to make them.] @@ -706,6 +722,8 @@ initialized with the @var{port} argument. @node File Ports @subsubsection File Ports +@cindex File port +@cindex Port, file The following procedures are used to open file ports. See also @ref{Ports and File Descriptors, open}, for an interface @@ -866,6 +884,8 @@ Determine whether @var{obj} is a port that is related to a file. @node String Ports @subsubsection String Ports +@cindex String port +@cindex Port, string The following allow string ports to be opened by analogy to R4R* file port facilities: @@ -931,6 +951,8 @@ but trying to extract the file descriptor number will fail. @node Soft Ports @subsubsection Soft Ports +@cindex Soft port +@cindex Port, soft A @dfn{soft-port} is a port based on a vector of procedures capable of accepting or delivering characters. It allows emulation of I/O ports. @@ -986,6 +1008,8 @@ For example: @node Void Ports @subsubsection Void Ports +@cindex Void port +@cindex Port, void This kind of port causes any data to be discarded when written to, and always returns the end-of-file object when read from. @@ -1010,6 +1034,8 @@ documentation for @code{open-file} in @ref{File Ports}. @node C Port Interface @subsubsection C Port Interface +@cindex C port interface +@cindex Port, C interface This section describes how to use Scheme ports from C. @@ -1119,6 +1145,7 @@ is set. @node Port Implementation @subsubsection Port Implementation +@cindex Port implemenation This section describes how to implement a new port type in C. diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi index faf57d6b1..341bcf450 100644 --- a/doc/ref/posix.texi +++ b/doc/ref/posix.texi @@ -1388,17 +1388,17 @@ and @code{command-line} above. @var{argv} is an array of null-terminated strings, as in a C @code{main} function. @var{argc} is the number of strings in -@var{argv}, or if it's negative then a @code{NULL} entry in @var{argv} -marks its end. +@var{argv}, or if it's negative then a @code{NULL} in @var{argv} marks +its end. @var{first} is an extra string put at the start of the arguments, or @code{NULL} for no such extra. This is a convenient way to pass the program name after advancing @var{argv} to strip option arguments. +Eg.@: @example @{ char *progname = argv[0]; - int i; for (argv++; argv[0] != NULL && argv[0][0] == '-'; argv++) @{ /* munch option ... */ @@ -1409,7 +1409,7 @@ program name after advancing @var{argv} to strip option arguments. @end example This sort of thing is often done at startup under -@code{scm_boot_guile} with any options handled at the C level removed. +@code{scm_boot_guile} with options handled at the C level removed. The given strings are all copied, so the C data is not accessed again once @code{scm_set_program_arguments} returns. @end deftypefn @@ -1836,7 +1836,13 @@ specified processes. @subsection Signals @cindex signal -Procedures to raise, handle and wait for signals. +The following procedures raise, handle and wait for signals. + +Scheme code signal handlers are run via a system async (@pxref{System +asyncs}), so they're called in the handler's thread at the next safe +opportunity. Generally this is after any currently executing +primitive procedure finishes (which could be a long time for +primitives that wait for an external event). @deffn {Scheme Procedure} kill pid sig @deffnx {C Function} scm_kill (pid, sig) @@ -1961,47 +1967,72 @@ action is to either terminate the current process or invoke a handler procedure. The return value is unspecified. @end deffn -@deffn {Scheme Procedure} sleep i -@deffnx {C Function} scm_sleep (i) -Wait for the given number of seconds (an integer) or until a signal -arrives. The return value is zero if the time elapses or the number -of seconds remaining otherwise. -@end deffn - -@deffn {Scheme Procedure} usleep i -@deffnx {C Function} scm_usleep (i) -Sleep for @var{i} microseconds. @code{usleep} is not available on -all platforms. [FIXME: so what happens when it isn't?] -@end deffn - -@deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds -@deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds) -Set the timer specified by @var{which_timer} according to the given -@var{interval_seconds}, @var{interval_microseconds}, -@var{value_seconds}, and @var{value_microseconds} values. - -Return information about the timer's previous setting. +@deffn {Scheme Procedure} sleep secs +@deffnx {Scheme Procedure} usleep usecs +@deffnx {C Function} scm_sleep (secs) +@deffnx {C Function} scm_usleep (usecs) +Wait the given period @var{secs} seconds or @var{usecs} microseconds +(both integers). If a signal arrives the wait stops and the return +value is the time remaining, in seconds or microseconds respectively. +If the period elapses with no signal the return is zero. -The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, -and @code{ITIMER_PROF}. +On most systems the process scheduler is not microsecond accurate and +the actual period slept by @code{usleep} might be rounded to a system +clock tick boundary, which might be 10 milliseconds for instance. -The return value will be a list of two cons pairs representing the -current state of the given timer. The first pair is the seconds and -microseconds of the timer @code{it_interval}, and the second pair is -the seconds and microseconds of the timer @code{it_value}. +See @code{scm_std_sleep} and @code{scm_std_usleep} for equivalents at +the C level (@pxref{Blocking}). @end deffn @deffn {Scheme Procedure} getitimer which_timer +@deffnx {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds periodic_seconds periodic_microseconds @deffnx {C Function} scm_getitimer (which_timer) -Return information about the timer specified by @var{which_timer}. +@deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, periodic_seconds, periodic_microseconds) +Get or set the periods programmed in certain system timers. These +timers have a current interval value which counts down and on reaching +zero raises a signal. An optional periodic value can be set to +restart from there each time, for periodic operation. +@var{which_timer} is one of the following values + +@defvar ITIMER_REAL +A real-time timer, counting down elapsed real time. At zero it raises +@code{SIGALRM}. This is like @code{alarm} above, but with a higher +resolution period. +@end defvar + +@defvar ITIMER_VIRTUAL +A virtual-time timer, counting down while the current process is +actually using CPU. At zero it raises @code{SIGVTALRM}. +@end defvar + +@defvar ITIMER_PROF +A profiling timer, counting down while the process is running (like +@code{ITIMER_VIRTUAL}) and also while system calls are running on the +process's behalf. At zero it raises a @code{SIGPROF}. + +This timer is intended for profiling where a program is spending its +time (by looking where it is when the timer goes off). +@end defvar + +@code{getitimer} returns the current timer value and its programmed +restart value, as a list containing two pairs. Each pair is a time in +seconds and microseconds: @code{((@var{interval_secs} +. @var{interval_usecs}) (@var{periodic_secs} +. @var{periodic_usecs}))}. + +@code{setitimer} sets the timer values similarly, in seconds and +microseconds (which must be integers). The periodic value can be zero +to have the timer run down just once. The return value is the timer's +previous setting, in the same form as @code{getitimer} returns. -The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, -and @code{ITIMER_PROF}. +@example +(setitimer ITIMER_REAL + 5 500000 ;; first SIGALRM in 5.5 seconds time + 2 0) ;; then repeat every 2 seconds +@end example -The return value will be a list of two cons pairs representing the -current state of the given timer. The first pair is the seconds and -microseconds of the timer @code{it_interval}, and the second pair is -the seconds and microseconds of the timer @code{it_value}. +Although the timers are programmed in microseconds, the actual +accuracy might not be that high. @end deffn diff --git a/doc/ref/slib.texi b/doc/ref/slib.texi index a719494b6..7d433cc17 100644 --- a/doc/ref/slib.texi +++ b/doc/ref/slib.texi @@ -27,41 +27,11 @@ slib, The SLIB Manual}). For example, @result{} #t @end example -Note that the following Guile core functions are overridden by -@code{(ice-9 slib)}, to implement SLIB specified semantics. - -@table @code -@item delete-file -@findex delete-file -Returns @code{#t} for success or @code{#f} for failure -(@pxref{Input/Output,,, slib, The SLIB Manual}), as opposed to the -Guile core version unspecified for success and throwing an error for -failure (@pxref{File System}). - -@c `provide' is also exported by ice-9 slib, but its definition in -@c slib require.scm is the same as guile boot-9.scm, so believe -@c nothing needs to be said about that. - -@item provided? -@findex provided? -Accepts a feature specification containing @code{and} and @code{or} -forms combining symbols (@pxref{Feature,,, slib, The SLIB Manual}), as -opposed to the Guile core taking only plain symbols (@pxref{Feature -Manipulation}). - -@item open-file -@findex open-file -Takes a symbol @code{r}, @code{rb}, @code{w} or @code{wb} for the open -mode (@pxref{Input/Output,,, slib, The SLIB Manual}), as opposed to -the Guile core version taking a string (@pxref{File Ports}). - -@item system -@findex system -Returns a plain exit code 0 to 255 (@pxref{System Interface,,, slib, -The SLIB Manual}), as opposed to the Guile core version returning a -wait status that must be examined with @code{status:exit-val} etc -(@pxref{Processes}). -@end table +A few Guile core functions are overridden by the SLIB setups; for +example the SLIB version of @code{delete-file} returns a boolean +indicating success or failure, whereas the Guile core version throws +an error for failure. In general (and as might be expected) when SLIB +is loaded it's the SLIB specifications which are followed. @menu * SLIB installation:: |