Changeset 35529 in project


Ignore:
Timestamp:
05/07/18 19:17:22 (3 months ago)
Author:
felix
Message:

man/5: corrections, added shit, [re]moved shit

Location:
wiki/man/5
Files:
2 deleted
21 edited

Legend:

Unmodified
Added
Removed
  • wiki/man/5/Accessing external objects

    r35316 r35529  
    33[[toc:]]
    44
    5 == Accessing external objects
     5== Accessing externally defined data
    66
    7 === foreign-code
    8 
    9 <macro>(foreign-code STRING ...)</macro>
    10 
    11 Executes the embedded C/C++ code {{STRING ...}}, which should
    12 be a sequence of C statements, which are executed and return an unspecified result.
    13 
    14 <enscript highlight=scheme>
    15 (foreign-code "doSomeInitStuff();")     =>  #<unspecified>
    16 </enscript>
    17 
    18 Code wrapped inside {{foreign-code}} may not invoke callbacks into Scheme.
    19 
    20 
    21 === foreign-value
    22 
    23 <macro>(foreign-value CODE TYPE)</macro>
    24 
    25 Evaluates the embedded C/C++ expression {{CODE}} (which may be a string or symbol), returning a value of type given
    26 in the foreign-type specifier {{TYPE}}.
    27 
    28 <enscript highlight=scheme>
    29 (print (foreign-value "my_version_string" c-string))
    30 </enscript>
    31 
    32 
    33 === foreign-declare
    34 
    35 <macro>(foreign-declare STRING ...)</macro>
    36 
    37 Include given strings verbatim into header of generated file.
    38 
    39 
    40 === define-foreign-type
    41 
    42 <macro>(define-foreign-type NAME TYPE [ARGCONVERT [RETCONVERT]])</macro>
    43 
    44 Defines an alias for {{TYPE}} with the name {{NAME}} (a symbol).
    45 {{TYPE}} may be a type-specifier or a string naming a C type. The
    46 namespace of foreign type specifiers is separate from the normal
    47 Scheme namespace.  The optional arguments {{ARGCONVERT}} and
    48 {{RETCONVERT}} should evaluate to procedures that map argument- and
    49 result-values to a value that can be transformed to {{TYPE}}:
    50 
    51 <enscript highlight=scheme>
    52 (define-foreign-type char-vector
    53   nonnull-c-string
    54   (compose list->string vector->list)
    55   (compose list->vector string->list) )
    56 
    57 (define strlen
    58   (foreign-lambda int "strlen" char-vector) )
    59 
    60 (strlen '#(#\a #\b #\c))                      ==> 3
    61 
    62 (define memset
    63   (foreign-lambda char-vector "memset" char-vector char int) )
    64 
    65 (memset '#(#_ #_ #_) #\X 3)                ==> #(#\X #\X #\X)
    66 </enscript>
    67 
    68 Foreign type-definitions are only visible in the compilation-unit in which
    69 they are defined, so use {{include}} to use the same definitions
    70 in multiple files.
    71 
    72 
    73 === foreign-type-size
    74 
    75 <macro>(foreign-type-size TYPE)</macro>
    76 
    77 Returns the size of the storage required to hold values of the
    78 given foreign type {{TYPE}}. This is basically equivalent to
    79 
    80 <enscript highlight=scheme>
    81 (foreign-value "sizeof(TYPE)" size_t)
    82 </enscript>
    83 
    84 but also handles user-defined types and allows "TYPE" to be a string,
    85 which will be given literally to the {{sizeof}} operator.
    86 
    87 
    88 === define-foreign-variable
    89 
    90 <macro>(define-foreign-variable NAME TYPE [STRING])</macro>
    91 
    92 Defines a foreign variable of name {{NAME}} (a symbol). {{STRING}}
    93 should be the real name of a foreign variable or parameterless
    94 macro. If {{STRING}} is not given, then the variable name {{NAME}}
    95 will be converted to a string and used instead. All references and
    96 assignments (via {{set!}}) are modified to correctly convert values
    97 between Scheme and C representation. This foreign variable can only be
    98 accessed in the current compilation unit, but the name can be
    99 lexically shadowed.  Note that {{STRING}} can name an arbitrary C
    100 expression. If no assignments are performed, then {{STRING}} doesn't
    101 even have to specify an lvalue.
    102 See that {{define-foreign-variable}} will not generate C declarations
    103 or memory allocation code; use it to include references to variables
    104 in external C code. To actually create Scheme variables visible from C,
    105 use {{define-external}} (see the Manual section on
    106 [[Callbacks]]).
    107 For example, the following code:
    108 <enscript lang="scheme">
    109 (import foreign)
    110 (define-foreign-variable x double "var_x")
    111 (print x)
    112 </enscript>
    113 will not work, because a reference to {{var_x}} will be inserted in the C code,
    114 but no declaration will be included (this can be easily verified by translating
    115 the program into C with {{csc -t program.scm}}). Changing the second line to
    116 {{(define-external x double 0.5)}} will work (and the value 0.5 will be printed).
    117 === foreign-lambda
    118 
    119 <macro>(foreign-lambda RETURNTYPE NAME ARGTYPE ...)</macro>
    120 
    121 Represents a
    122 binding to an external routine. This form can be used in the position
    123 of an ordinary {{lambda}} expression. {{NAME}} specifies the
    124 name of the external procedure and should be a string or a symbol.
    125 
    126 
    127 === foreign-lambda*
    128 
    129 <macro>(foreign-lambda* RETURNTYPE ((ARGTYPE VARIABLE) ...) STRING ...)</macro>
    130 
    131 Similar to {{foreign-lambda}}, but instead of generating code to
    132 call an external function, the body of the C procedure is directly given
    133 in {{STRING ...}}:
    134 
    135 <enscript highlight=scheme>
    136 (define my-strlen
    137   (foreign-lambda* int ((c-string str))
    138     "int n = 0;
    139      while(*(str++)) ++n;
    140      C_return(n);") )
    141 
    142 (my-strlen "one two three")             ==> 13
    143 </enscript>
    144 
    145 For obscure technical reasons you should use the {{C_return}} macro instead of the normal {{return}} statement
    146 to return a result from the foreign lambda body as some cleanup code has to be run before execution
    147 commences in the calling code.
    148 
    149 === foreign-safe-lambda
    150 
    151 <macro>(foreign-safe-lambda RETURNTYPE NAME ARGTYPE ...)</macro>
    152 
    153 This is similar to {{foreign-lambda}}, but also allows the called
    154 function to call Scheme functions. See [[Callbacks]].
    155 
    156 
    157 === foreign-safe-lambda*
    158 
    159 <macro>(foreign-safe-lambda* RETURNTYPE ((ARGTYPE VARIABLE)...) STRING ...)</macro>
    160 
    161 This is similar to {{foreign-lambda*}}, but also allows the called
    162 function to call Scheme functions and allocate Scheme data-objects. See [[Callbacks]].
    163 
    164 
    165 
    166 === foreign-primitive
    167 
    168 <macro>(foreign-primitive [RETURNTYPE] ((ARGTYPE VARIABLE) ...) STRING ...)</macro>
    169 
    170 This is also similar to {{foreign-lambda*}} but the code will be
    171 executed in a ''primitive'' CPS context, which means it will not
    172 actually return, but call its continuation on exit. This means that code
    173 inside this form may allocate Scheme data on the C stack (the
    174 ''nursery'') with {{C_alloc}} (see below). You can return multiple
    175 values inside the body of the {{foreign-primitive}} form by using
    176 the following C code:
    177 
    178 <enscript highlight=scheme>
    179 C_word av[N + 2] = { C_SCHEME_UNDEFINED, C_k, X1, ... };
    180 C_values(N + 2, av);
    181 </enscript>
    182 
    183 where {{N}} is the number of values to be returned, and {{X1, ...}}
    184 are the results, which should be Scheme data objects. When returning
    185 multiple values, the return-type should be omitted.  Of course, if you
    186 have to dynamically compute the values, you do not have to use C's
    187 array initialization syntax, but you can just assign them one by one.
    188 
    189 Returning just a single value can still be done via the {{C_return(...)}} macro.
     7For a list of the special forms that allow definition of Scheme procedures
     8that access native C/C++ code, consult the documentation on the
     9[[(chicken foreign)|Module (chicken foreign)]] module. The remainder
     10of this chapter merely explains a few special cases.
    19011
    19112== Returning large objects or chunks of memory to Scheme
  • wiki/man/5/C interface

    r35318 r35529  
    16071607
    16081608---
    1609 Previous: [[Locations]]
     1609Previous: [[Embedding]]
    16101610
    16111611Next: [[Data representation]]
  • wiki/man/5/Deviations from the standard

    r35525 r35529  
    11[[tags: manual]]
    22
    3 == Confirmed deviations
     3== Confirmed deviations from R5RS
    44
    55Identifiers are by default case-sensitive (see [[Using the compiler]]).
     
    2525=== Environments and non-standard syntax
    2626
    27 In addition to the standard bindings {{scheme-report-environment}} and
     27In addition to the standard bindings, {{scheme-report-environment}} and
    2828{{null-environment}} contain additional non-standard bindings for the
    2929following syntactic forms: {{import}}, {{require-extension}},
  • wiki/man/5/Embedding

    r35316 r35529  
    349349Previous: [[Foreign type specifiers]]
    350350
    351 Next: [[Callbacks]]
     351Next: [[C interface]]
  • wiki/man/5/Extensions to the standard

    r35525 r35529  
    33[[toc:]]
    44
    5 == Extensions to the standard
     5== Extensions to the R5RS standard
    66
    77=== Identifiers
     
    1414The brackets {{[ ... ]}} and the braces {{ { ... } }} are
    1515provided as an alternative syntax for {{( ... )}}.  A number of reader
    16 extensions is provided. See [[Non-standard read syntax]].
    17 
    18 === Non-standard macros
    19 
    20 Numerous non-standard macros are provided. See
    21 [[Non-standard macros and special forms]] for more information.
    22 
    23 === Non-standard procedures
     16extensions is provided.
     17
     18=== Non-standard procedures and syntax
    2419
    2520CHICKEN provides numerous non-standard procedures. See the manual
    26 sections on library units for more information.
     21sections on the included library modules ([[Included modules]]) for more information.
    2722
    2823=== User defined character names
     
    4843The latter is encoded in UTF-8 format.
    4944
    50 The third argument to {{substring}} is optional and defaults to the length
    51 of the string.
    52 
    53 === {{exit}}
    54 
    55 The {{exit}} procedure exits a program right away and does ''not'' invoke pending {{dynamic-wind}} thunks.
    56 
    57 
    5845== Non-standard read syntax
    5946
     
    9683=== Location Expression
    9784
    98  #$EXPRESSION
     85<read> #$EXPRESSION</read>
    9986
    10087An abbreviation for {{(location EXPRESSION)}}.
  • wiki/man/5/Included modules

    r35525 r35529  
    2020* [[Module (chicken csi)]] : Features specific to {{csi}}
    2121* [[Module (chicken errno)]] : Accessing the C "errno" variable
     22* [[Module (chicken eval)]] : Evaluation hooks
    2223* [[Module (chicken file)]] : High-level API for file system manipulations
    2324* [[Module (chicken file posix)]] : POSIX-specific file manipulations
     
    2829* [[Module (chicken gc)]] : Interacting with the garbage collector
    2930* [[Module (chicken io)]] : Reading and writing to files and other ports
     31* [[Module (chicken irregex)]] : Regular expressions
    3032* [[Module (chicken keyword)]] : Operations on keyword objects
    3133* [[Module (chicken load)]] : Loading code from files
  • wiki/man/5/Interface to external functions and variables

    r35528 r35529  
    1212* [[Foreign type specifiers]] 
    1313* [[Embedding]]               
    14 * [[Callbacks]]                   
    15 * [[Locations]]                   
    1614* [[C interface]]       
    1715* [[Data representation]]         
     
    2018Previous: [[Included modules]]
    2119
    22 Next: [[Declarations]]
     20Next: [[Modules]]
  • wiki/man/5/Module (chicken base)

    r35372 r35529  
    77standard and other essential features.
    88
    9 This module is used by default, unless the program is compiled with
     9This module is used by default, unless a program is compiled with
    1010the {{-explicit-use}} option.
    1111
     
    12811281* {{(version ID NUMBER)}} is equivalent to {{ID}}, but checks at compile-time whether the extension named {{ID}} is installed and whether its version is equal or higher than {{NUMBER}}. {{NUMBER}} may be a string or a number, the comparison is done lexicographically (using {{string>=?}}).
    12821282
    1283 TODO: Document declare (keep the "declarations" section?)
    1284 
    12851283=== Process shutdown
    12861284
  • wiki/man/5/Module (chicken eval)

    r34271 r35529  
    55
    66This module provides a handful of hooks that allow more fine-grained
    7 control over how the [standard procedure eval](Module scheme#eval)
    8 behaves.
     7control over how the standard procedure {{eval}} behaves.
    98
    109=== Custom eval handlers
  • wiki/man/5/Module (chicken fixnum)

    r34077 r35529  
    55
    66Because CHICKEN supports a full numeric tower, operations can
    7 sometimes have a lot of overhead to simply detect the type of numbers
     7sometimes incur a substantial overhead to simply detect the type of numbers
    88you're passing in.  When you know you're definitely dealing only with
    99fixnums, you can choose to use fixnum-specific operations to avoid
  • wiki/man/5/Module (chicken flonum)

    r34052 r35529  
    55
    66Because CHICKEN supports a full numeric tower, operations can
    7 sometimes have a lot of overhead to simply detect the type of numbers
     7sometimes incur a subtantial overhead to simply detect the type of numbers
    88you're passing in.  When you know you're definitely dealing only with
    99flonums, you can choose to use flonum-specific operations to avoid
  • wiki/man/5/Module (chicken foreign)

    r34052 r35529  
    44== Module (chicken foreign)
    55
    6 TODO: This should contain all the stuff from "Accessing external
    7 objects", but maybe other stuff too.  It makes more sense to also have
    8 "foreign type specifiers" in here, I think.
     6This module provides a ''foreign function interface'' to access externally
     7defined functions and variables in C-compatible languages, as well as
     8operating-system specific functionality.
     9
     10Note that this interface is source-based, since CHICKEN translates
     11Scheme code to C. It is not binary, as in many other Scheme implementations.
     12
     13Several special forms of this interface refer to ''foreign type specifies'',
     14consult the [[relevant chapter|Foreign type specifies]] of this manual for
     15more information.
     16
     17
     18== Accessing external objects
     19
     20=== foreign-code
     21
     22<macro>(foreign-code STRING ...)</macro>
     23
     24Executes the embedded C/C++ code {{STRING ...}}, which should
     25be a sequence of C statements, which are executed and return an unspecified result.
     26
     27<enscript highlight=scheme>
     28(foreign-code "doSomeInitStuff();")     =>  #<unspecified>
     29</enscript>
     30
     31Code wrapped inside {{foreign-code}} may not invoke callbacks into Scheme.
     32
     33
     34=== foreign-value
     35
     36<macro>(foreign-value CODE TYPE)</macro>
     37
     38Evaluates the embedded C/C++ expression {{CODE}} (which may be a string or symbol), returning a value of type given
     39in the foreign-type specifier {{TYPE}}.
     40
     41<enscript highlight=scheme>
     42(print (foreign-value "my_version_string" c-string))
     43</enscript>
     44
     45
     46=== foreign-declare
     47
     48<macro>(foreign-declare STRING ...)</macro>
     49
     50Include given strings verbatim into header of generated file.
     51
     52
     53=== define-foreign-type
     54
     55<macro>(define-foreign-type NAME TYPE [ARGCONVERT [RETCONVERT]])</macro>
     56
     57Defines an alias for {{TYPE}} with the name {{NAME}} (a symbol).
     58{{TYPE}} may be a type-specifier or a string naming a C type. The
     59namespace of foreign type specifiers is separate from the normal
     60Scheme namespace.  The optional arguments {{ARGCONVERT}} and
     61{{RETCONVERT}} should evaluate to procedures that map argument- and
     62result-values to a value that can be transformed to {{TYPE}}:
     63
     64<enscript highlight=scheme>
     65(define-foreign-type char-vector
     66  nonnull-c-string
     67  (compose list->string vector->list)
     68  (compose list->vector string->list) )
     69
     70(define strlen
     71  (foreign-lambda int "strlen" char-vector) )
     72
     73(strlen '#(#\a #\b #\c))                      ==> 3
     74
     75(define memset
     76  (foreign-lambda char-vector "memset" char-vector char int) )
     77
     78(memset '#(#_ #_ #_) #\X 3)                ==> #(#\X #\X #\X)
     79</enscript>
     80
     81Foreign type-definitions are only visible in the compilation-unit in which
     82they are defined, so use {{include}} to use the same definitions
     83in multiple files.
     84
     85
     86=== foreign-type-size
     87
     88<macro>(foreign-type-size TYPE)</macro>
     89
     90Returns the size of the storage required to hold values of the
     91given foreign type {{TYPE}}. This is basically equivalent to
     92
     93<enscript highlight=scheme>
     94(foreign-value "sizeof(TYPE)" size_t)
     95</enscript>
     96
     97but also handles user-defined types and allows "TYPE" to be a string,
     98which will be given literally to the {{sizeof}} operator.
     99
     100
     101=== define-foreign-variable
     102
     103<macro>(define-foreign-variable NAME TYPE [STRING])</macro>
     104
     105Defines a foreign variable of name {{NAME}} (a symbol). {{STRING}}
     106should be the real name of a foreign variable or parameterless
     107macro. If {{STRING}} is not given, then the variable name {{NAME}}
     108will be converted to a string and used instead. All references and
     109assignments (via {{set!}}) are modified to correctly convert values
     110between Scheme and C representation. This foreign variable can only be
     111accessed in the current compilation unit, but the name can be
     112lexically shadowed.  Note that {{STRING}} can name an arbitrary C
     113expression. If no assignments are performed, then {{STRING}} doesn't
     114even have to specify an lvalue.
     115See that {{define-foreign-variable}} will not generate C declarations
     116or memory allocation code; use it to include references to variables
     117in external C code. To actually create Scheme variables visible from C,
     118use {{define-external}} (see the Manual section on
     119[[Callbacks]]).
     120For example, the following code:
     121<enscript lang="scheme">
     122(import foreign)
     123(define-foreign-variable x double "var_x")
     124(print x)
     125</enscript>
     126will not work, because a reference to {{var_x}} will be inserted in the C code,
     127but no declaration will be included (this can be easily verified by translating
     128the program into C with {{csc -t program.scm}}). Changing the second line to
     129{{(define-external x double 0.5)}} will work (and the value 0.5 will be printed).
     130
     131=== foreign-lambda
     132
     133<macro>(foreign-lambda RETURNTYPE NAME ARGTYPE ...)</macro>
     134
     135Represents a
     136binding to an external routine. This form can be used in the position
     137of an ordinary {{lambda}} expression. {{NAME}} specifies the
     138name of the external procedure and should be a string or a symbol.
     139
     140
     141=== foreign-lambda*
     142
     143<macro>(foreign-lambda* RETURNTYPE ((ARGTYPE VARIABLE) ...) STRING ...)</macro>
     144
     145Similar to {{foreign-lambda}}, but instead of generating code to
     146call an external function, the body of the C procedure is directly given
     147in {{STRING ...}}:
     148
     149<enscript highlight=scheme>
     150(define my-strlen
     151  (foreign-lambda* int ((c-string str))
     152    "int n = 0;
     153     while(*(str++)) ++n;
     154     C_return(n);") )
     155
     156(my-strlen "one two three")             ==> 13
     157</enscript>
     158
     159For obscure technical reasons you should use the {{C_return}} macro instead of the normal {{return}} statement
     160to return a result from the foreign lambda body as some cleanup code has to be run before execution
     161commences in the calling code.
     162
     163=== foreign-safe-lambda
     164
     165<macro>(foreign-safe-lambda RETURNTYPE NAME ARGTYPE ...)</macro>
     166
     167This is similar to {{foreign-lambda}}, but also allows the called
     168function to call Scheme functions. See [[Callbacks]].
     169
     170
     171=== foreign-safe-lambda*
     172
     173<macro>(foreign-safe-lambda* RETURNTYPE ((ARGTYPE VARIABLE)...) STRING ...)</macro>
     174
     175This is similar to {{foreign-lambda*}}, but also allows the called
     176function to call Scheme functions and allocate Scheme data-objects. See [[Callbacks]].
     177
     178
     179
     180=== foreign-primitive
     181
     182<macro>(foreign-primitive [RETURNTYPE] ((ARGTYPE VARIABLE) ...) STRING ...)</macro>
     183
     184This is also similar to {{foreign-lambda*}} but the code will be
     185executed in a ''primitive'' CPS context, which means it will not
     186actually return, but call its continuation on exit. This means that code
     187inside this form may allocate Scheme data on the C stack (the
     188''nursery'') with {{C_alloc}} (see below). You can return multiple
     189values inside the body of the {{foreign-primitive}} form by using
     190the following C code:
     191
     192<enscript highlight=scheme>
     193C_word av[N + 2] = { C_SCHEME_UNDEFINED, C_k, X1, ... };
     194C_values(N + 2, av);
     195</enscript>
     196
     197where {{N}} is the number of values to be returned, and {{X1, ...}}
     198are the results, which should be Scheme data objects. When returning
     199multiple values, the return-type should be omitted.  Of course, if you
     200have to dynamically compute the values, you do not have to use C's
     201array initialization syntax, but you can just assign them one by one.
     202
     203Returning just a single value can still be done via the {{C_return(...)}} macro.
     204
     205
     206== Callbacks
     207
     208
     209To enable an external C function to call back to Scheme, the form
     210{{foreign-safe-lambda}} (or {{foreign-safe-lambda*}})
     211has to be used. This generates special code to save and restore important
     212state information during execution of C code. There are two ways of
     213calling Scheme procedures from C: the first is to invoke the runtime
     214function {{C_callback}} with the closure to be called and the number
     215of arguments.  The second is to define an externally visible wrapper
     216function around a Scheme procedure with the {{define-external}}
     217form.
     218
     219Note: the names of all functions, variables and macros exported by the
     220CHICKEN runtime system start with {{C_}}. It is advisable to
     221use a different naming scheme for your own code to avoid name clashes.
     222Callbacks (defined by {{define-external}})
     223do not capture the lexical environment.
     224
     225Non-local exits leaving the scope of the invocation of a callback from Scheme into C
     226will not remove the C call-frame from the stack (and will result in a memory
     227leak).  '''Note:''' The same applies to
     228SRFI-18 threading, which is implemented with {{call/cc}};
     229additionally, if you enter one callback, switch threads and then exit
     230a different callback, your program is likely to crash.
     231
     232
     233=== define-external
     234
     235<macro>(define-external [QUALIFIERS] (NAME (ARGUMENTTYPE1 VARIABLE1) ...) RETURNTYPE BODY ...)</macro><br>
     236<macro>(define-external NAME TYPE [INIT])</macro>
     237
     238The first form defines an externally callable Scheme
     239procedure. {{NAME}} should be a symbol, which, when converted to a
     240string, represents a legal C identifier. {{ARGUMENTTYPE1 ...}} and
     241{{RETURNTYPE}} are foreign type specifiers for the argument variables
     242{{VAR1 ...}} and the result, respectively.  {{QUALIFIERS}}
     243is an optional qualifier for the foreign procedure definition, like
     244{{__stdcall}}.
     245
     246<enscript highlight=scheme>
     247(define-external (foo (c-string x)) int (string-length x))
     248</enscript>
     249
     250The second form of {{define-external}} can be used to define
     251variables that are accessible from foreign code. It declares
     252a global variable named by the symbol {{NAME}} that
     253has the type {{TYPE}}. {{INIT}} can be an arbitrary
     254expression that is used to initialize the variable. {{NAME}} is
     255accessible from Scheme just like any other foreign variable defined by
     256{{define-foreign-variable}}. 
     257
     258<enscript highlight=scheme>
     259(define-external foo int 42)
     260((foreign-lambda* int ()
     261  "C_return(foo);"))           ==> 42
     262</enscript>
     263
     264'''Note:''' don't be tempted to
     265assign strings or bytevectors to external variables. Garbage collection
     266moves those objects around, so it is a very bad idea to assign pointers
     267to heap-data. If you have to do so, then copy the data object into
     268statically allocated memory (for example by using {{object-evict}}).
     269
     270Results of type {{scheme-object}} returned by {{define-external}}
     271are always allocated in the secondary heap, that is, not in the stack.
     272
     273=== C_callback
     274
     275 [C function] C_word C_callback (C_word closure, int argc)
     276
     277This function can be used to invoke the Scheme procedure {{closure}}.
     278{{argc}} should contain the number of arguments that are passed to
     279the procedure on the temporary stack. Values are put onto the temporary
     280stack with the {{C_save}} macro.
     281
     282=== C_callback_adjust_stack
     283
     284 [C function] void C_callback_adjust_stack (C_word *ptr, int size)
     285
     286The runtime-system uses the stack as a special allocation area and
     287internally holds pointers to estimated limits to distinguish between
     288Scheme data objects inside the stack from objects outside of it.  If
     289you invoke callbacks at wildly differing stack-levels, these limits
     290may shift from invocation to invocation. Callbacks defined with
     291{{define-external}} will perform appropriate adjustments
     292automatically, but if you invoke {{C_callback}} manually, you should
     293perform a {{C_callback_adjust_stack}} to make sure the internal limits
     294are set properly. {{ptr}} should point to some data object on the
     295stack and {{size}} is the number of words contained in the data object
     296(or some estimate). The call will make sure the limits are adjusted so
     297that the value pointed to by {{ptr}} is located in the stack.
     298
     299== Locations
     300
     301It is also possible to define variables containing unboxed C data,
     302so called ''locations''. It should be noted that locations may
     303only contain simple data, that is: everything that fits into a
     304machine word, and double-precision floating point values.
     305
     306
     307
     308=== define-location
     309
     310<macro>(define-location NAME TYPE [INIT])</macro>
     311
     312Identical to {{(define-external NAME TYPE [INIT])}}, but the variable
     313is not accessible from outside of the current compilation unit (it is
     314declared {{static}}).
     315
     316=== let-location
     317
     318<macro>(let-location ((NAME TYPE [INIT]) ...) BODY ...)</macro>
     319
     320Defines a lexically bound location.
     321
     322=== location
     323
     324<macro>(location NAME)</macro><br>
     325<macro>(location X)</macro>
     326<read>#$</read>
     327
     328This form returns a pointer object
     329that contains the address of the variable {{NAME}}.
     330If the argument to {{location}} is not a location defined by {{define-location}},
     331{{define-external}} or {{let-location}}, then
     332
     333 (location X)
     334
     335is essentially equivalent to
     336
     337 (make-locative X)
     338
     339(See the [[Unit lolevel#locatives|manual section on locatives]] for more
     340information about locatives)
     341
     342Note that {{(location X)}} may be abbreviated as {{#$X}}.
     343
     344<enscript highlight=scheme>
     345(define-external foo int)
     346((foreign-lambda* void (((c-pointer int) ip)) "*ip = 123;")
     347  (location foo))
     348foo                                                                    ==> 123
     349</enscript>
     350
     351This facility is especially useful in situations, where a C function
     352returns more than one result value:
     353
     354<enscript highlight=scheme>
     355#>
     356#include <math.h>
     357<#
     358
     359(define modf
     360  (foreign-lambda double "modf" double (c-pointer double)) )
     361
     362(let-location ([i double])
     363  (let ([f (modf 1.99 (location i))])
     364    (print "i=" i ", f=" f) ) )
     365</enscript>
     366
     367See [[/location-and-c-string-star|location and c-string*]]
     368for a tip on returning a {{c-string*}} type.
     369
     370{{location}} returns a value of type {{c-pointer}}, when given
     371the name of a callback-procedure defined with {{define-external}}.
    9372
    10373---
  • wiki/man/5/Module (chicken keyword)

    r34052 r35529  
    5858
    5959---
    60 Previous: [[Module (chicken io)]]
     60Previous: [[Module (chicken irregex)]]
    6161
    62 Next: [[Module (chicken keyword)]]
     62Next: [[Module (chicken load)]]
  • wiki/man/5/Module (chicken module)

    r35463 r35529  
    44== Module (chicken module)
    55
    6 This module provides special forms to define your own modules and to
    7 control visibility of identifiers in those modules.
    8 
    9 TODO: Move everything from the old "Modules" page here?  It's a bit
    10 weird considering that's halfway between tutorial and reference.
    11 
    12 === current-module
    13 
    14 <macro>(current-module)</macro>
    15 
    16 This will expand to a symbol which matches the current module's name
    17 when used inside a module.  If not inside a module (i.e., at
    18 toplevel), this expands to {{#f}}.
     6The functionality in this module is available by default. See
     7[[Modules]] for more information.
    198
    209---
  • wiki/man/5/Module (chicken repl)

    r34294 r35529  
    4040
    4141
    42 ==== reset
     42=== reset
    4343
    4444<procedure>(reset)</procedure>
  • wiki/man/5/Module (chicken syntax)

    r35470 r35529  
    55
    66This module has support for syntax- and module handling. This module
    7 is used by default, unless the program is compiled with the
     7is used by default, unless a program is compiled with the
    88{{-explicit-use}} option.
    99
  • wiki/man/5/Module (chicken tcp)

    r34052 r35529  
    55
    66This module provides basic facilities for communicating over TCP
    7 sockets.  The socket interface should be mostly compatible to the one
    8 found in PLT Scheme.
     7sockets. 
    98
    109All errors related to failing network operations will raise a condition
  • wiki/man/5/Module r4rs

    r35283 r35529  
    77{{scheme}} module which are from the R4RS standard.
    88
    9 This is every procedure and macro from [[scheme]] except for
     9This is every procedure and macro from [[scheme|Module scheme]] except for
    1010{{dynamic-wind}}, {{eval}}, {{call-with-values}} and {{values}}.
    1111
  • wiki/man/5/Module scheme

    r35470 r35529  
    88Algorithmic Language Scheme''.
    99
    10 This module is used by default, unless the program is compiled with
     10This module is used by default, unless a program is compiled with
    1111the {{-explicit-use}} option.
    1212
     
    239239
    240240Semantics: An if expression is evaluated as follows: first, <test> is
    241 evaluated. If it yields a true value (see [[#booleans|the section
     241evaluated. If it yields a true value (see [[#Booleans|the section
    242242about booleans]] below), then <consequent> is evaluated and its
    243243value(s) is(are) returned. Otherwise <alternate> is evaluated and its
     
    297297Semantics: A cond expression is evaluated by evaluating the <test>
    298298expressions of successive <clause>s in order until one of them
    299 evaluates to a true value (see [[#booleans|the section about
     299evaluates to a true value (see [[#Booleans|the section about
    300300booleans]] below). When a <test> evaluates to a true value, then the
    301301remaining <expression>s in its <clause> are evaluated in order, and
     
    382382The <test> expressions are evaluated from left to right, and the value
    383383of the first expression that evaluates to a false value (see
    384 [[#booleans|the section about booleans]]) is returned. Any remaining
     384[[#Booleans|the section about booleans]]) is returned. Any remaining
    385385expressions are not evaluated. If all the expressions evaluate to true
    386386values, the value of the last expression is returned. If there are no
     
    396396The <test> expressions are evaluated from left to right, and the value
    397397of the first expression that evaluates to a true value (see
    398 [[#booleans|the section about booleans]]) is returned. Any remaining
     398[[#Booleans|the section about booleans]]) is returned. Any remaining
    399399expressions are not evaluated. If all expressions evaluate to false
    400400values, the value of the last expression is returned. If there are no
     
    539539
    540540Each iteration begins by evaluating <test>; if the result is false
    541 (see [[#booleans|the section about booleans]]), then the <command>
     541(see [[#Booleans|the section about booleans]]), then the <command>
    542542expressions are evaluated in order for effect, the <step> expressions
    543543are evaluated in some unspecified order, the <variable>s are bound to
     
    26822682numerical predicates.
    26832683
    2684 <procedure>(substring string start end)</procedure><br>
     2684<procedure>(substring string start [end])</procedure><br>
    26852685
    26862686String must be a string, and start and end must be exact integers
     
    26912691Substring returns a newly allocated string formed from the characters
    26922692of string beginning with index start (inclusive) and ending with index
    2693 end (exclusive).
     2693end (exclusive). The {{end}} argument is optional and defaults to the
     2694length of the string.
    26942695
    26952696<procedure>(string-append string ...)</procedure><br>
  • wiki/man/5/Modules

    r35468 r35529  
    433433functor body.
    434434
     435=== current-module
     436
     437<macro>(current-module)</macro>
     438
     439This will expand to a symbol which matches the current module's name
     440when used inside a module.  If not inside a module (i.e., at
     441toplevel), this expands to {{#f}}.
     442
    435443
    436444---
    437 Previous: [[Macros]]
     445Previous: [[Interface to external functions and variables]]
    438446
    439447Next: [[Types]]
  • wiki/man/5/The User's Manual

    r35528 r35529  
    1616* [[Included modules]] : A reference to CHICKEN's core module library
    1717* [[Interface to external functions and variables]] : Accessing C/C++ code and data
     18* [[Modules]] : How CHICKEN manages namespaces
     19* [[Types]] : Optionally typed Scheme code
    1820* [[Declarations]] : Compiler declarations
    1921* [[Extensions]] : Packaging and installing extension libraries
Note: See TracChangeset for help on using the changeset viewer.