~ chicken-core (chicken-5) c22f038cec0fe5956fcebd5112b7b334163d3b44
commit c22f038cec0fe5956fcebd5112b7b334163d3b44 Author: felix <felix@call-with-current-continuation.org> AuthorDate: Fri Aug 27 20:01:56 2010 +0200 Commit: felix <felix@call-with-current-continuation.org> CommitDate: Fri Aug 27 20:01:56 2010 +0200 merged manual changes from wiki diff --git a/manual/Accessing external objects b/manual/Accessing external objects index e81ef6c4..06b90d06 100644 --- a/manual/Accessing external objects +++ b/manual/Accessing external objects @@ -88,7 +88,7 @@ See that {{define-foreign-variable}} will not generate C declarations or memory allocation code; use it to include references to variables in external C code. To actually create Scheme variables visible from C, use {{define-external}} (see the Manual section on -[[http://chicken.wiki.br/man/4/Callbacks|Callbacks]]). +[[http://wiki.call-cc.org/man/4/Callbacks|Callbacks]]). For example, the following code: <enscript lang="scheme"> (import foreign) @@ -168,6 +168,53 @@ where {{N}} is the number of values to be returned, and {{X1, ...}} are the results, which should be Scheme data objects. When returning multiple values, the return-type should be omitted. +== Returning large objects or chunks of memory to Scheme + +When you call a C function which needs to return quantities of data, several issues arise: +* the size of the nursery is limited, so C_alloc can cause stack overflow +* if you malloc in C, and intend to leave it there, and directly access parts of that data from Scheme, you will need C accessor functions to pinpoint the parts you need and return them as Scheme objects; you will also need a finalizer if you intend for this data to be garbage-collected +* building up lists or other complex Scheme structures from individual pairs, or putting non-immediate objects into vectors, is cumbersome in C + +So some would advise you to just return a pointer to Scheme, use memcpy or any other function(s) which you need to get the data into Chicken-managed memory and into the desired kind of data structure, then free the C data. For this example, we are trying to return an array of doubles into an f64vector; we can accomplish that by adding a specialized copy function to the C library being integrated: + +<enscript highlight=C> +void CopyResults(double* vector) { + memcpy(vector, bezierBuffer, totalOutputPoints * sizeof(double)); +} + +// The original C function which takes an array of doubles, +// does some sort of transmogrification, +// retains a new malloc'd array of the results +// and returns the count +int GenerateResults(double* vector, int count) { + ... +} +</enscript> + +and the "egg" which calls the C functions can be implemented like this: + +<enscript highlight=scheme> +(module memcpy-demo (input->output) + (import chicken scheme foreign) + (use srfi-4) + + (define CopyResults (foreign-lambda void "CopyResults" f64vector)) + + (define GenerateResults (foreign-lambda integer "GenerateResults" f64vector integer)) + + (define (input->output input) + (let* ([size (GenerateResults input (f64vector-length input))] + [vect (make-f64vector size)]) + (printf "returned size ~a~%" size) + (CopyResults vect) + vect))) + +</enscript> + +The foreign-lambda takes care of the details in this case so that an f64vector allocated in the nursery can be treated as a plain old array of doubles in C (assuming your C compiler uses 64-bit values for double). + +Various eggs provide other examples, and some of them do it more efficiently too, but this method is relatively clean and compact. + --- Previous: [[Interface to external functions and variables]] diff --git a/manual/C interface b/manual/C interface index 79648682..821f0541 100644 --- a/manual/C interface +++ b/manual/C interface @@ -17,7 +17,7 @@ Saves the Scheme data object {{x}} on the temporary stack. ==== C_restore - [C macro] void C_restore + [C macro] C_word C_restore Pops and returns the topmost value from the temporary stack. diff --git a/manual/Deployment b/manual/Deployment index 7be21c1b..1330f163 100644 --- a/manual/Deployment +++ b/manual/Deployment @@ -6,7 +6,7 @@ CHICKEN generates fully native binaries that can be distributed like normal C/C++ programs. There are various methods of deployment, -depending on platform, linkage, external dependencies and wether +depending on platform, linkage, external dependencies and whether the application should be built from sources or precompiled and whether the CHICKEN runtime-libraries are expected on the destination system or if the application should be completely self-contained. diff --git a/manual/Extensions b/manual/Extensions index 83f45cee..e17197a1 100644 --- a/manual/Extensions +++ b/manual/Extensions @@ -473,7 +473,7 @@ program to remove one or more extensions from the local repository: The hello module was just a shared library, and not a module. To create an extension that exports syntax see the chapter on -[[http://chicken.wiki.br/man/4/Modules%20and%20macros|Modules and +[[http://wiki.call-cc.org/man/4/Modules%20and%20macros|Modules and macros]]. We will show a simple example here: a module {{my-lib}} that exports one macro ({{prog1}}) and one procedure ({{my-sum}}): @@ -567,7 +567,7 @@ Next, it should be possible to load the library: When running {{chicken-install}} with an argument {{NAME}}, for which no associated {{.setup}} file exists, then it will try to download the extension via HTTP from the CHICKEN code repository at -[[http://chicken.wiki.br/svn/chicken-eggs/]]. Extensions that are +[[http://code.call-cc.org/svn/chicken-eggs/]]. Extensions that are required to compile and/or use the requested extension are downloaded and installed automatically. @@ -677,7 +677,7 @@ the tools). You can install eggs with - chicken-install -p ~/my_eggs <package> + chicken-install -p ~/myeggs <package> See that the argument to chicken-install is just {{~/myeggs}}, while everywhere else it's {{~/myeggs/lib/chicken/5}}. diff --git a/manual/Getting started b/manual/Getting started index 9432723a..ae127455 100644 --- a/manual/Getting started +++ b/manual/Getting started @@ -157,14 +157,14 @@ The master CHICKEN website is basic information about CHICKEN, downloads, and pointers to other key resources. -The CHICKEN wiki ([[http://chicken.wiki.br]]) contains the most +The CHICKEN wiki ([[http://wiki.call-cc.org]]) contains the most current version of the User's manual, along with various tutorials and other useful documents. The list of eggs is at -[[http://chicken.wiki.br/chicken-projects/egg-index-4.html#category-list]]. +[[http://wiki.call-cc.org/chicken-projects/egg-index-4.html#category-list]]. A very useful search facility for questions about CHICKEN is found at -[[http://www.callcc.org]]. The CHICKEN issue tracker is at -[[http://www.irp.oist.jp/trac/chicken/wiki]]. +[[http://chickadee.call-cc.org]]. The CHICKEN issue tracker is at +[[http://bugs.call-cc.org]]. The CHICKEN community has two major mailing lists. If you are a CHICKEN user, {{chicken-users}} @@ -318,7 +318,7 @@ We can now load this file and try out the function. The '''read-eval-print loop''' ('''REPL''') is the component of the Scheme system that ''reads'' a Scheme expression, ''eval''uates it, and ''prints'' out the result. The REPL's prompt can be customized -(see the [[http:Using%20the%20interpreter|`Using the Interpreter']]) +(see the [[Using the Interpreter]]) but the default prompt, showing the number of the form, is quite convenient. diff --git a/manual/Locations b/manual/Locations index c4fd2b4b..4129cf7e 100644 --- a/manual/Locations +++ b/manual/Locations @@ -42,8 +42,8 @@ is essentially equivalent to (make-locative X) -(See the manual chapter or {{locatives}} for more information about -locatives. +(See the [[Unit lolevel#locatives|manual section on locatives]] for more +information about locatives) Note that {{(location X)}} may be abbreviated as {{#$X}}. @@ -51,7 +51,7 @@ Note that {{(location X)}} may be abbreviated as {{#$X}}. (define-external foo int) ((foreign-lambda* void (((c-pointer int) ip)) "*ip = 123;") (location foo)) -foo ==> 123 +foo ==> 123 </enscript> This facility is especially useful in situations, where a C function @@ -70,7 +70,7 @@ returns more than one result value: (print "i=" i ", f=" f) ) ) </enscript> -See [[http://chicken.wiki.br/location-and-c-string-star|location and c-string*]] +See [[http://wiki.call-cc.org/location-and-c-string-star|location and c-string*]] for a tip on returning a {{c-string*}} type. {{location}} returns a value of type {{c-pointer}}, when given diff --git a/manual/Non-standard macros and special forms b/manual/Non-standard macros and special forms index 58feca78..1eca9831 100644 --- a/manual/Non-standard macros and special forms +++ b/manual/Non-standard macros and special forms @@ -265,7 +265,7 @@ exist in the Scheme namespace and can be lexically shadowed. If the value is mutable, then the compiler is careful to preserve its identity. {{CONST}} may be any constant expression, and may also refer to constants defined via {{define-constant}} previously. -This for should only be used at top-level. +This form should only be used at top-level. ==== define-inline @@ -308,7 +308,7 @@ name of a globally or locally bound procedure. Any direct call to this procedure will be transformed before compilation, which allows arbitrary rewritings of function calls. -{{TRANSFORMER}} can be a {{syntax-rules}} expression or an explicit-renaming transforme +{{TRANSFORMER}} can be a {{syntax-rules}} expression or an explicit-renaming transformer procedure. Returning the original form in an explicit-renaming macro or simply "falling trough" all patterns in a {{syntax-rules}} form will keep the original expression and compile it normally. @@ -322,12 +322,12 @@ module. {{define-compiler-syntax}} should only be used at top-level. Local compiler-syntax can be defined with {{let-compiler-syntax}}. -<scheme> +<enscript highlight=scheme> (define-compiler-syntax + (syntax-rules () ((_) 1) ((_ x 0) x) ) ) -</scheme> +</enscript> If no transformer is given, then {{(define-compiler-syntax NAME)}} removes any compiler-syntax definitions for {{NAME}}. @@ -338,7 +338,7 @@ any compiler-syntax definitions for {{NAME}}. <macro>(let-compiler-syntax ((NAME [TRANSFORMER]) ...) BODY ...)</macro> Allows definition local compiler macros, which are only applicable inside {{BODY ...}}. -By not providing a transformer expression, compiler-syntax for specific identifiers +By not providing a {{TRANSFORMER}} expression, compiler-syntax for specific identifiers can be temporarily disabled. @@ -463,17 +463,22 @@ Expands by selecting feature clauses. This form is allowed to appear in non-topl Predefined feature-identifiers are "situation" specific: -; compile : {{eval}}, {{library}}, {{match}}, {{compiling}}, {{srfi-11}}, {{srfi-15}}, {{srfi-31}}, {{srfi-26}}, {{srfi-16}}, {{utils}}, {{regex}}, {{srfi-4}}, {{match}}, {{srfi-1}}, {{srfi-69}}, {{srfi-28}}, {{extras}}, {{srfi-8}}, {{srfi-6}}, {{srfi-2}}, {{srfi-0}}, {{srfi-10}}, {{srfi-9}}, {{srfi-55}}, {{srfi-61}} {{chicken}}, {{srfi-23}}, {{srfi-30}}, {{srfi-39}}, {{srfi-62}}, {{srfi-17}}, {{srfi-12}}. +; compile : {{chicken}}, {{compiling}}, {{library}}, {{eval}}, {{extras}}, {{utils}}, {{regex}}, {{srfi-0}}, {{srfi-1}}, {{srfi-2}}, {{srfi-4}}, {{srfi-6}}, {{srfi-8}}, {{srfi-9}}, {{srfi-10}}, {{srfi-11}}, {{srfi-12}}, {{srfi-15}}, {{srfi-16}}, {{srfi-17}}, {{srfi-23}}, {{srfi-26}}, {{srfi-28}}, {{srfi-30}}, {{srfi-31}}, {{srfi-39}}, {{srfi-55}}, {{srfi-61}}, {{srfi-62}}, {{srfi-69}} -; load : {{srfi-69}}, {{srfi-28}}, {{extras}}, {{srfi-8}}, {{srfi-6}}, {{srfi-2}}, {{srfi-0}}, {{srfi-10}}, {{srfi-9}}, {{srfi-55}}, {{srfi-61}}, {{chicken}}, {{srfi-23}}, {{srfi-30}}, {{srfi-39}}, {{srfi-62}}, {{srfi-17}}, {{srfi-12}}. {{library}} is implicit. +; load : {{chicken}}, {{extras}}, {{srfi-0}}, {{srfi-2}}, {{srfi-6}}, {{srfi-8}}, {{srfi-9}}, {{srfi-10}}, {{srfi-12}}, {{srfi-17}}, {{srfi-23}}, {{srfi-28}}, {{srfi-30}}, {{srfi-39}}, {{srfi-55}}, {{srfi-61}}, {{srfi-62}}, {{srfi-69}}. {{library}} is implicit. -; eval : {{match}}, {{csi}}, {{srfi-11}}, {{srfi-15}}, {{srfi-31}}, {{srfi-26}}, {{srfi-16}}, {{srfi-69}}, {{srfi-28}}, {{extras}}, {{srfi-8}}, {{srfi-6}}, {{srfi-2}}, {{srfi-0}}, {{srfi-10}}, {{srfi-9}}, {{srfi-55}}, {{srfi-61}}, {{chicken}}, {{srfi-23}}, {{srfi-30}}, {{srfi-39}}, {{srfi-62}}, {{srfi-17}}, {{srfi-12}}. {{library}} is implicit. +; eval : {{csi}}, {{chicken}}, {{extras}}, {{srfi-0}}, {{srfi-2}}, {{srfi-6}}, {{srfi-8}}, {{srfi-9}}, {{srfi-10}}, {{srfi-11}}, {{srfi-12}}, {{srfi-15}}, {{srfi-16}}, {{srfi-17}}, {{srfi-23}}, {{srfi-26}}, {{srfi-28}}, {{srfi-30}}, {{srfi-31}}, {{srfi-39}}, {{srfi-55}}, {{srfi-61}}, {{srfi-62}}, {{srfi-69}}. {{library}} is implicit. -The following feature-identifiers are available in all situations: {{(machine-byte-order)}}, {{(machine-type)}}, {{(software-type)}}, {{(software-version)}}, where the actual feature-identifier is platform dependent. +The following feature-identifier classes are available in all situations: +{{(machine-byte-order)}}, {{(machine-type)}}, {{(software-type)}}, +{{(software-version)}}, where the actual feature-identifier is platform +dependent. -In addition the following feature-identifiers may exist: {{applyhook}}, {{extraslot}}, {{ptables}}, {{dload}}. +In addition the following feature-identifiers may exist: {{cross-chicken}}, +{{dload}}, {{manyargs}}, {{ptables}}. -For further information, see the documentation for [[http://srfi.schemers.org/srfi-0/srfi-0.html|SRFI-0]]. +For further information, see the documentation for +[[http://srfi.schemers.org/srfi-0/srfi-0.html|SRFI-0]]. ==== ensure diff --git a/manual/Unit data-structures b/manual/Unit data-structures index 80cc7e48..a89111e5 100644 --- a/manual/Unit data-structures +++ b/manual/Unit data-structures @@ -372,7 +372,7 @@ is equivalent to <procedure>(string-split STRING [DELIMITER-STRING [KEEPEMPTY]])</procedure> -Split string into substrings separated by the given delimiters. If +Split string into substrings delimited by any of the characters given in the delimiter string. If no delimiters are specified, a string comprising the tab, newline and space characters is assumed. If the parameter {{KEEPEMPTY}} is given and not {{#f}}, then empty @@ -381,6 +381,7 @@ substrings are retained: <enscript highlight=scheme> (string-split "one two three") ==> ("one" "two" "three") (string-split "foo:bar::baz:" ":" #t) ==> ("foo" "bar" "" "baz" "") +(string-split "foo:bar:baz,quux,zot" ":," ) ==> ("foo" "bar" "baz" "quux" "zot") </enscript> diff --git a/manual/Unit eval b/manual/Unit eval index c0b2a5ae..959aa336 100644 --- a/manual/Unit eval +++ b/manual/Unit eval @@ -13,11 +13,11 @@ option. <procedure>(load FILE [EVALPROC])</procedure> -Loads and evaluates expressions from the given source file, which may -be either a string or an input port. Each expression read is passed to -{{EVALPROC}} (which defaults to {{eval}}). On platforms that -support it (currently native Windows, Linux ELF and Solaris), {{load}} can be used -to load compiled programs: +Loads and evaluates expressions from the given source file, which may be either +a string or an input port. Each expression read is passed to {{EVALPROC}} +(which defaults to {{eval}}). On platforms that support it (currently BSD, +Haiku, MacOS X, Linux, Solaris, and Windows), {{load}} can be used to load +compiled programs: % cat x.scm (define (hello) (print "Hello!")) @@ -60,7 +60,7 @@ If {{PRINTER}} is given and not false, then each expression is printed before evaluation by applying the expression to the value of this argument, which should be a one-argument procedure. -See also the [[http://chicken.wiki.br/Parameters#load-verbose|load-verbose]] parameter. +See also the [[http://wiki.call-cc.org/Parameters#load-verbose|load-verbose]] parameter. ==== load-library <procedure>(load-library UNIT [LIBRARYFILE])</procedure> @@ -75,7 +75,7 @@ are checked for the required unit: * a file named ''{{<UNIT>.so}}'' * the files given in the parameter {{dynamic-load-libraries}} -If the unit is not found, an error is signaled. When the library unit +If the unit is not found, an error is signaled. When the library unit can be successfully loaded, a feature-identifier named {{UNIT}} is registered. If the feature is already registered before loading, the {{load-library}} does nothing. @@ -153,7 +153,7 @@ are currently loaded, or {{#f}} otherwise. If the extension library {{ID}} is not already loaded into the system, then {{require}} will lookup the location of the shared extension library and load it. If {{ID}} names a library-unit of -the base system, then it is loaded via {{load-library}}. If no +the base system, then it is loaded via {{load-library}}. If no extension library is available for the given ID, then an attempt is made to load the file {{ID.so}} or {{ID.scm}} (in that order) from one of the following locations: @@ -169,7 +169,7 @@ from one of the following locations: <procedure>(chicken-home)</procedure> -Returns a string given the installation directory (usually {{/usr/local/share/chicken}} on UNIX-like systems). +Returns a string which represents the installation directory (usually {{/usr/local/share/chicken}} on UNIX-like systems). As a last option, if the environment variable {{CHICKEN_PREFIX}} is set, then {{chicken-home}} will return {{$CHICKEN_PREFIX/share}}. diff --git a/manual/Unit lolevel b/manual/Unit lolevel index 172d166e..0d5d6c2d 100644 --- a/manual/Unit lolevel +++ b/manual/Unit lolevel @@ -15,9 +15,9 @@ This unit uses the {{srfi-4}} and {{extras}} units. The abstract class of ''pointer'' is divided into 2 categories: -; ''pointer object'' : is a foreign pointer object, a tagged foreign pointer object (see {{Tagged pointers}}), or a SWIG-pointer. +; ''pointer object'' : is a foreign pointer object, a [[#Tagged pointers|tagged foreign pointer object]], or a SWIG-pointer. -; ''pointer-like object'' " is a closure, port, locative (see {{Locatives}}, or a pointer object. +; ''pointer-like object'' : is a closure, port, [[#Locatives|locative]], or a pointer object. SWIG-pointers are currently an issue due to "bitrot" in the SWIG Chicken translator. While they are considered a pointer object unexpected results are @@ -486,7 +486,7 @@ static memory are copied back into garbage collected storage. <procedure>(move-memory! FROM TO [BYTES [FROM-OFFSET [TO-OFFSET]]])</procedure> Copies {{BYTES}} bytes of memory from {{FROM}} to {{TO}}. {{FROM}} and {{TO}} -may be strings, blobs, SRFI-4 number-vectors (see: @ref{Unit srfi-4}), memory +may be strings, blobs, [[Unit srfi-4|SRFI-4 number-vectors]], memory mapped files, foreign pointers (as obtained from a call to {{foreign-lambda}}, for example), tagged-pointers or locatives. if {{BYTES}} is not given and the size of the source or destination operand is known then the maximal number of diff --git a/manual/Unit posix b/manual/Unit posix index f236e3d6..3fb190e2 100644 --- a/manual/Unit posix +++ b/manual/Unit posix @@ -96,7 +96,7 @@ then {{(current-directory DIR)}} is equivalent to {{(change-directory DIR)}}. <procedure>(create-directory NAME #!optional PARENTS?)</procedure> Creates a directory with the pathname {{NAME}}. If the {{PARENTS?}} argument -is given and not false, any nonextant parent directories are also created. +is given and not false, any nonexistent parent directories are also created. ==== delete-directory @@ -422,7 +422,7 @@ return an inexact integer. <procedure>(regular-file? FILENAME)</procedure> -Returns true, if {{FILENAME}} names a regular file. +Returns true, if {{FILENAME}} names a regular file (not a directory or symbolic link). ==== file-owner diff --git a/manual/Using the compiler b/manual/Using the compiler index 2de86f3a..416e5770 100644 --- a/manual/Using the compiler +++ b/manual/Using the compiler @@ -5,7 +5,7 @@ The {{csc}} compiler driver provides a convenient interface to the basic Scheme-to-C translator ({{chicken}}) and takes care -for compiliong and linking the generated C files into executable +for compiling and linking the generated C files into executable code. Enter csc -help diff --git a/manual/Using the interpreter b/manual/Using the interpreter index 92cf9580..1d00f661 100644 --- a/manual/Using the interpreter +++ b/manual/Using the interpreter @@ -12,7 +12,7 @@ and expressions interactively. where {{FILENAME}} specifies a file with Scheme source-code. If the extension of the source file is {{.scm}}, it may be omitted. The -runtime options described in [[http://galinha.ucpel.tche.br/Using%20the%20compiler#Compiler%20command%20line%20format|Compiler command line format]] are also available +runtime options described in [[Using%20the%20compiler#Compiler%20command%20line%20format|Compiler command line format]] are also available for the interpreter. If the environment variable {{CSI_OPTIONS}} is set to a list of options, then these options are additionally passed to every direct or indirect invocation of {{csi}}. Please note that @@ -127,7 +127,7 @@ The toplevel loop understands a number of special commands: ; ,? : Show summary of available toplevel commands. -; ,l FILENAME ... : Load files with given {{FILENAME}}s. +; ,l FILENAME ... : Load files with given {{FILENAME}}s ; ,ln FILENAME ... : Load files and print result(s) of each top-level expression. @@ -260,21 +260,18 @@ textual description of the object to the passed output-port. For example: On platforms that support it, it is possible to get auto-completion of symbols, history (over different {{csi}} sessions) and a more feature-full editor for the expressions you type -using the [[http://www.call-with-current-continuation.org/eggs/readline.html]] egg by +using the [[http://wiki.call-cc.org/eggref/4/readline]] egg by Tony Garnock Jones. It is very useful for interactive use of csi. To enable it install the egg and put this in your {{~/.csirc}} file: - (use readline regex) - (current-input-port (make-gnu-readline-port)) - (gnu-history-install-file-manager - (string-append (or (getenv "HOME") ".") "/.csi.history")) - -More details are available in [[http://www.call-with-current-continuation.org/eggs/readline.html|the egg's documentation]]. - - -=== Note about libraries automatically loaded in the interpreter +<enscript highlight=scheme> +(use readline regex) +(current-input-port (make-gnu-readline-port)) +(gnu-history-install-file-manager + (string-append (or (getenv "HOME") ".") "/.csi.history")) +</enscript> The interpreter {{csi}} internally requires some routines from the {{ports}} and {{extras}} library units and loads them automatically diff --git a/manual/faq b/manual/faq index 7abf0381..9e066755 100644 --- a/manual/faq +++ b/manual/faq @@ -86,7 +86,7 @@ numbers) are more than sufficient; - Dispatching of arithmetic operations is more efficient. There is an extension based on the GNU Multiprecision Package that implements most of the full -numeric tower, see [[http://chicken.wiki.br/egg/numbers|numbers]]. +numeric tower, see [[http://wiki.call-cc.org/egg/numbers|numbers]]. ==== Does CHICKEN support native threads? @@ -632,7 +632,7 @@ It should contain the path where you want eggs to be installed: $ chicken-install -init ~/eggs/lib/chicken/5 $ chicken-install -p ~/eggs/ extensionname -In order to make programs (including csi) see these eggs, you should set this variable when you run them. See the [[http://chicken.wiki.br/man/4/Extensions#changing-repository-location|Extensions/Changing repository location]] section of the manual for more information on that. +In order to make programs (including csi) see these eggs, you should set this variable when you run them. See the [[http://wiki.call-cc.org/man/4/Extensions#changing-repository-location|Extensions/Changing repository location]] section of the manual for more information on that. Alternatively, you can call the {{repository-path}} Scheme procedure before loading the eggs, as in:Trap