1 ! Copyright (C) 2009 Jeremy Hughes.
2 ! See http://factorcode.org/license.txt for BSD license.
3 USING: help.markup help.syntax kernel quotations sequences
4 strings alien alien.c-types alien.data math byte-arrays ;
8 : $memory-note ( arg -- )
9 drop "This word returns a pointer to unmanaged memory."
12 : $c-ptr-note ( arg -- )
13 drop "Does nothing if its argument is a non false c-ptr."
16 : $see-article ( arg -- )
17 drop { "See " { $vocab-link "alien.inline" } "." }
21 HELP: ?malloc-byte-array
26 { $description "Does nothing if input is an alien, otherwise assumes it is a byte array and calls "
27 { $snippet "malloc-byte-array" } "."
29 { $notes $memory-note } ;
32 { $var-description "For wrapping C pointers in a structure factor can dispatch on." } ;
36 { "alien-wrapper" alien-wrapper }
37 { "alien-wrapper'" alien-wrapper }
39 { $description "Called immediately after unmarshalling. Useful for automatically casting to subtypes." } ;
43 { "?" "a generalized boolean" }
46 { $description "Marshalls objects to bool." }
47 { $notes "Will treat " { $snippet "0" } " as " { $snippet "t" } "." } ;
51 { "?/seq" "t/f or sequence" }
54 { $description "When the argument is a sequence, returns a pointer to an array of bool, "
55 "otherwise returns a pointer to a single bool value."
57 { $notes { $list $c-ptr-note $memory-note } } ;
64 { $description "Takes a one or two dimensional array of generalized booleans "
65 "and returns a pointer to the equivalent C structure."
67 { $notes { $list $c-ptr-note $memory-note } } ;
69 HELP: marshall-primitive
74 { $description "Marshall numbers to C primitives."
76 "Factor marshalls numbers to primitives for FFI calls, so all "
77 "this word does is convert " { $snippet "t" } " to " { $snippet "1" }
78 ", " { $snippet "f" } " to " { $snippet "0" } ", and lets anything else "
79 "pass through untouched."
84 { "n/seq" "number or sequence" }
87 { $description $see-article }
88 { $notes { $list $c-ptr-note $memory-note } } ;
95 { $description $see-article }
96 { $notes { $list $c-ptr-note $memory-note } } ;
98 HELP: marshall-char**-or-strings
100 { "seq" "a sequence of strings" }
103 { $description "Marshalls an array of strings or characters to an array of C strings." }
104 { $notes { $list $c-ptr-note $memory-note } } ;
106 HELP: marshall-char*-or-string
108 { "n/string" "a number or string" }
111 { $description "Marshalls a string to a C string or a number to a pointer to " { $snippet "char" } "." }
112 { $notes { $list $c-ptr-note $memory-note } } ;
114 HELP: marshall-double*
116 { "n/seq" "a number or sequence" }
119 { $description $see-article }
120 { $notes { $list $c-ptr-note $memory-note } } ;
122 HELP: marshall-double**
127 { $description $see-article }
128 { $notes { $list $c-ptr-note $memory-note } } ;
130 HELP: marshall-float*
132 { "n/seq" "a number or sequence" }
135 { $description $see-article }
136 { $notes { $list $c-ptr-note $memory-note } } ;
138 HELP: marshall-float**
143 { $description $see-article }
144 { $notes { $list $c-ptr-note $memory-note } } ;
148 { "n/seq" "a number or sequence" }
151 { $description $see-article }
152 { $notes { $list $c-ptr-note $memory-note } } ;
159 { $description $see-article }
160 { $notes { $list $c-ptr-note $memory-note } } ;
164 { "n/seq" "a number or sequence" }
167 { $description $see-article }
168 { $notes { $list $c-ptr-note $memory-note } } ;
170 HELP: marshall-long**
175 { $description $see-article }
176 { $notes { $list $c-ptr-note $memory-note } } ;
178 HELP: marshall-longlong*
180 { "n/seq" "a number or sequence" }
183 { $description $see-article }
184 { $notes { $list $c-ptr-note $memory-note } } ;
186 HELP: marshall-longlong**
191 { $description $see-article }
192 { $notes { $list $c-ptr-note $memory-note } } ;
194 HELP: marshall-non-pointer
196 { "alien-wrapper/byte-array" "an alien-wrapper or byte-array" }
197 { "byte-array" byte-array }
199 { $description "Converts argument to a byte array." }
200 { $notes "Not meant to be called directly. Use the output of " { $link marshaller } " instead." } ;
202 HELP: marshall-pointer
207 { $description "Converts argument to a C pointer." }
208 { $notes "Can marshall the following types: " { $snippet "alien, f, byte-array, alien-wrapper, struct-array" } "." } ;
210 HELP: marshall-short*
212 { "n/seq" "a number or sequence" }
215 { $description $see-article }
216 { $notes { $list $c-ptr-note $memory-note } } ;
218 HELP: marshall-short**
223 { $description $see-article }
224 { $notes { $list $c-ptr-note $memory-note } } ;
226 HELP: marshall-uchar*
228 { "n/seq" "a number or sequence" }
231 { $description $see-article }
232 { $notes { $list $c-ptr-note $memory-note } } ;
234 HELP: marshall-uchar**
239 { $description $see-article }
240 { $notes { $list $c-ptr-note $memory-note } } ;
244 { "n/seq" "a number or sequence" }
247 { $description $see-article }
248 { $notes { $list $c-ptr-note $memory-note } } ;
250 HELP: marshall-uint**
255 { $description $see-article }
256 { $notes { $list $c-ptr-note $memory-note } } ;
258 HELP: marshall-ulong*
260 { "n/seq" "a number or sequence" }
263 { $description $see-article }
264 { $notes { $list $c-ptr-note $memory-note } } ;
266 HELP: marshall-ulong**
271 { $description $see-article }
272 { $notes { $list $c-ptr-note $memory-note } } ;
274 HELP: marshall-ulonglong*
276 { "n/seq" "a number or sequence" }
279 { $description $see-article }
280 { $notes { $list $c-ptr-note $memory-note } } ;
282 HELP: marshall-ulonglong**
287 { $description $see-article }
288 { $notes { $list $c-ptr-note $memory-note } } ;
290 HELP: marshall-ushort*
292 { "n/seq" "a number or sequence" }
295 { $description $see-article }
296 { $notes { $list $c-ptr-note $memory-note } } ;
298 HELP: marshall-ushort**
303 { $description $see-article }
304 { $notes { $list $c-ptr-note $memory-note } } ;
306 HELP: marshall-void**
311 { $description "Marshalls a sequence of objects to an array of pointers to void." }
312 { $notes { $list $c-ptr-note $memory-note } } ;
316 { "type" "a C type string" }
319 { $description "Given a C type, returns a quotation that will marshall its argument to that type." } ;
321 HELP: out-arg-unmarshaller
323 { "type" "a C type string" }
326 { $description "Like " { $link unmarshaller } " but returns an empty quotation "
327 "for all types except pointers to non-const primitives."
330 HELP: class-unmarshaller
332 { "type" " a C type string" }
333 { "quot/f" quotation }
335 { $description "If in the vocab in which this word is called, there is a subclass of " { $link alien-wrapper }
336 " named after the type argument, " { $snippet "pointer-unmarshaller" } " will return a quotation which "
337 "wraps its argument in an instance of that subclass. In any other case it returns an empty quotation."
339 { $notes "Not meant to be called directly. Use the output of " { $link marshaller } " instead." } ;
341 HELP: primitive-marshaller
343 { "type" "a C type string" }
344 { "quot/f" "a quotation or f" }
346 { $description "Returns a quotation to marshall objects to the argument type." }
347 { $notes "Not meant to be called directly. Use the output of " { $link marshaller } " instead." } ;
349 HELP: primitive-unmarshaller
351 { "type" "a C type string" }
352 { "quot/f" "a quotation or f" }
354 { $description "Returns a quotation to unmarshall objects from the argument type." }
355 { $notes "Not meant to be called directly. Use the output of " { $link unmarshaller } " instead." } ;
357 HELP: struct-field-unmarshaller
359 { "type" "a C type string" }
362 { $description "Like " { $link unmarshaller } " but returns a quotation that "
363 "does not call " { $snippet "free" } " on its argument."
365 { $notes "Not meant to be called directly. Use the output of " { $link unmarshaller } " instead." } ;
367 HELP: struct-primitive-unmarshaller
369 { "type" "a C type string" }
370 { "quot/f" "a quotation or f" }
372 { $description "Like " { $link primitive-unmarshaller } " but returns a quotation that "
373 "does not call " { $snippet "free" } " on its argument." }
374 { $notes "Not meant to be called directly. Use the output of " { $link unmarshaller } " instead." } ;
376 HELP: struct-unmarshaller
378 { "type" "a C type string" }
379 { "quot/f" quotation }
381 { $description "Returns a quotation which wraps its argument in the subclass of "
382 { $link struct-wrapper } " which matches the " { $snippet "type" } " arg."
384 { $notes "Not meant to be called directly. Use the output of " { $link unmarshaller } " instead." } ;
387 { $var-description "For wrapping C structs in a structure factor can dispatch on." } ;
389 HELP: unmarshall-bool
394 { $description "Unmarshalls a number to a boolean." } ;
396 HELP: unmarshall-bool*
401 { $description "Unmarshalls a C pointer to a boolean." } ;
403 HELP: unmarshall-bool*-free
408 { $description "Unmarshalls a C pointer to a boolean and frees the pointer." } ;
410 HELP: unmarshall-char*
415 { $description $see-article } ;
417 HELP: unmarshall-char*-free
422 { $description $see-article } ;
424 HELP: unmarshall-char*-to-string
429 { $description "Unmarshalls a " { $snippet "char" } " pointer to a factor string." } ;
431 HELP: unmarshall-char*-to-string-free
436 { $description "Unmarshalls a " { $snippet "char" } " pointer to a factor string and frees the pointer." } ;
438 HELP: unmarshall-double*
443 { $description $see-article } ;
445 HELP: unmarshall-double*-free
450 { $description $see-article } ;
452 HELP: unmarshall-float*
457 { $description $see-article } ;
459 HELP: unmarshall-float*-free
464 { $description $see-article } ;
466 HELP: unmarshall-int*
471 { $description $see-article } ;
473 HELP: unmarshall-int*-free
478 { $description $see-article } ;
480 HELP: unmarshall-long*
485 { $description $see-article } ;
487 HELP: unmarshall-long*-free
492 { $description $see-article } ;
494 HELP: unmarshall-longlong*
499 { $description $see-article } ;
501 HELP: unmarshall-longlong*-free
506 { $description $see-article } ;
508 HELP: unmarshall-short*
513 { $description $see-article } ;
515 HELP: unmarshall-short*-free
520 { $description $see-article } ;
522 HELP: unmarshall-uchar*
527 { $description $see-article } ;
529 HELP: unmarshall-uchar*-free
534 { $description $see-article } ;
536 HELP: unmarshall-uint*
541 { $description $see-article } ;
543 HELP: unmarshall-uint*-free
548 { $description $see-article } ;
550 HELP: unmarshall-ulong*
555 { $description $see-article } ;
557 HELP: unmarshall-ulong*-free
562 { $description $see-article } ;
564 HELP: unmarshall-ulonglong*
569 { $description $see-article } ;
571 HELP: unmarshall-ulonglong*-free
576 { $description $see-article } ;
578 HELP: unmarshall-ushort*
583 { $description $see-article } ;
585 HELP: unmarshall-ushort*-free
590 { $description $see-article } ;
594 { "type" "a C type string" }
597 { $description "Given a C type, returns a quotation that will unmarshall values of that type." } ;
599 ARTICLE: "alien.marshall" "C marshalling"
600 { $vocab-link "alien.marshall" } " provides alien wrappers and marshalling words for the "
601 "automatic marshalling and unmarshalling of C function arguments, return values, and output parameters."
603 { $subheading "Important words" }
604 "Wrap an alien:" { $subsections alien-wrapper }
605 "Wrap a struct:" { $subsections struct-wrapper }
606 "Get the marshaller for a C type:" { $subsections marshaller }
607 "Get the unmarshaller for a C type:" { $subsections unmarshaller }
608 "Get the unmarshaller for an output parameter:" { $subsections out-arg-unmarshaller }
609 "Get the unmarshaller for a struct field:" { $subsections struct-field-unmarshaller }
611 "Other marshalling and unmarshalling words in this vocabulary are not intended to be "
614 "Most marshalling words allow non false c-ptrs to pass through unchanged."
616 { $subheading "Primitive marshallers" }
617 { $subsections marshall-primitive } "for marshalling primitive values."
618 { $subsections marshall-int* }
619 "marshalls a number or sequence of numbers. If argument is a sequence, returns a pointer "
620 "to a C array, otherwise returns a pointer to a single value."
621 { $subsections marshall-int** }
622 "marshalls a 1D or 2D array of numbers. Returns an array of pointers to arrays."
624 { $subheading "Primitive unmarshallers" }
625 { $snippet "unmarshall-<prim>*" } " and " { $snippet "unmarshall-<prim>*-free" }
626 " for all values of " { $snippet "<prim>" } " in " { $link primitive-types } "."
627 { $subsections unmarshall-int* }
628 "unmarshalls a pointer to primitive. Returns a number. "
629 "Assumes the pointer is not an array (if it is, only the first value is returned). "
630 "C functions that return arrays are not handled correctly by " { $snippet "alien.marshall" }
631 " and must be unmarshalled by hand."
632 { $subsections unmarshall-int*-free }
633 "unmarshalls a pointer to primitive, and then frees the pointer."
635 "Primitive values require no unmarshalling. The factor FFI already does this."
638 ABOUT: "alien.marshall"