source: project/chicken/trunk/manual/Accessing external objects @ 15143

Last change on this file since 15143 was 15143, checked in by felix winkelmann, 11 years ago

foreign-code accepts symbol argument

File size: 5.0 KB
Line 
1[[tags: manual]]
2
3[[toc:]]
4
5== Accessing external objects
6
7=== foreign-code
8
9 [syntax] (foreign-code STRING ...)
10
11Executes the embedded C/C++ code {{STRING ...}}, which should
12be 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
18Code wrapped inside {{foreign-code}} may not invoke callbacks into Scheme.
19
20
21=== foreign-value
22
23 [syntax] (foreign-value CODE TYPE)
24
25Evaluates the embedded C/C++ expression {{CODE}} (which may be a string or symbol), returning a value of type given
26in 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 [syntax] (foreign-declare STRING ...)
36
37Include given strings verbatim into header of generated file.
38
39
40=== define-foreign-type
41
42 [syntax] (define-foreign-type NAME TYPE [ARGCONVERT [RETCONVERT]])
43
44Defines 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
46namespace of foreign type specifiers is separate from the normal
47Scheme namespace.  The optional arguments {{ARGCONVERT}} and
48{{RETCONVERT}} should evaluate to procedures that map argument- and
49result-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
68Foreign type-definitions are only visible in the compilation-unit in which
69they are defined, so use {{include}} to use the same definitions
70in multiple files.
71
72
73=== define-foreign-variable
74
75 [syntax] (define-foreign-variable NAME TYPE [STRING])
76
77Defines a foreign variable of name {{NAME}} (a symbol). {{STRING}}
78should be the real name of a foreign variable or parameterless
79macro. If {{STRING}} is not given, then the variable name {{NAME}}
80will be converted to a string and used instead. All references and
81assignments (via {{set!}}) are modified to correctly convert values
82between Scheme and C representation. This foreign variable can only be
83accessed in the current compilation unit, but the name can be
84lexically shadowed.  Note that {{STRING}} can name an arbitrary C
85expression. If no assignments are performed, then {{STRING}} doesn't
86even have to specify an lvalue.
87
88
89=== foreign-lambda
90
91 [syntax] (foreign-lambda RETURNTYPE NAME ARGTYPE ...)
92
93Represents a
94binding to an external routine. This form can be used in the position
95of an ordinary {{lambda}} expression. {{NAME}} specifies the
96name of the external procedure and should be a string or a symbol.
97
98
99=== foreign-lambda*
100
101 [syntax] (foreign-lambda* RETURNTYPE ((ARGTYPE VARIABLE) ...) STRING ...)
102
103Similar to {{foreign-lambda}}, but instead of generating code to
104call an external function, the body of the C procedure is directly given
105in {{STRING ...}}:
106
107<enscript highlight=scheme>
108(define my-strlen
109  (foreign-lambda* int ((c-string str))
110    "int n = 0;
111     while(*(str++)) ++n;
112     C_return(n);") )
113
114(my-strlen "one two three")             ==> 13
115</enscript>
116
117For obscure technical reasons you should use the {{C_return}} macro instead of the normal {{return}} statement
118to return a result from the foreign lambda body as some cleanup code has to be run before execution
119commences in the calling code.
120
121=== foreign-safe-lambda
122
123 [syntax] (foreign-safe-lambda RETURNTYPE NAME ARGTYPE ...)
124
125This is similar to {{foreign-lambda}}, but also allows the called
126function to call Scheme functions and allocate Scheme data-objects. See [[Callbacks]].
127
128
129=== foreign-safe-lambda*
130
131 [syntax] (foreign-safe-lambda* RETURNTYPE ((ARGTYPE VARIABLE)...) STRING ...)
132
133This is similar to {{foreign-lambda*}}, but also allows the called
134function to call Scheme functions and allocate Scheme data-objects. See [[Callbacks]].
135
136
137
138=== foreign-primitive
139
140 [syntax] (foreign-primitive [RETURNTYPE] ((ARGTYPE VARIABLE) ...) STRING ...)
141
142This is also similar to {{foreign-lambda*}} but the code will be executed
143in a ''primitive'' CPS context, which means it will not actually return, but
144call it's continuation on exit. This means that code inside this form may
145allocate Scheme data on the C stack (the ''nursery'') with {{C_alloc}}
146(see below). If the {{RETURNTYPE}} is omitted it defaults to {{void}}.
147You can return multiple values inside the body of the {{foreign-primitive}}
148form by calling this C function:
149
150<enscript highlight=scheme>
151C_values(N + 2, C_SCHEME_UNDEFINED, C_k, X1, ...)
152</enscript>
153
154where {{N}} is the number of values to be returned, and {{X1, ...}} are the
155results, which should be Scheme data objects. When returning multiple values, the
156return-type should be omitted.
157
158---
159Previous: [[Interface to external functions and variables]]
160
161Next: [[Foreign type specifiers]]
Note: See TracBrowser for help on using the repository browser.