1 USING: alien alien.c-types help.syntax help.markup libc
2 kernel.private byte-arrays math strings hashtables alien.syntax
3 alien.strings sequences io.encodings.string debugger destructors
4 vocabs.loader classes.struct quotations kernel ;
8 { $values { "seq" sequence } { "c-type" "a C type" } { "array" byte-array } }
9 { $description "Outputs a freshly allocated byte-array whose elements are C type values from the given sequence." }
10 { $notes "The appropriate specialized array vocabulary must be loaded; otherwise, an error will be thrown. See the " { $vocab-link "specialized-arrays" } " vocabulary for details on the underlying sequence type constructed." }
11 { $errors "Throws an error if the type does not exist, the necessary specialized array vocabulary is not loaded, or the requested size is negative." } ;
14 { $values { "len" "a non-negative integer" } { "c-type" "a C type" } { "array" byte-array } }
15 { $description "Creates a byte array large enough to hold " { $snippet "n" } " values of a C type." }
16 { $notes "The appropriate specialized array vocabulary must be loaded; otherwise, an error will be thrown. See the " { $vocab-link "specialized-arrays" } " vocabulary for details on the underlying sequence type constructed." }
17 { $errors "Throws an error if the type does not exist, the necessary specialized array vocabulary is not loaded, or the requested size is negative." } ;
20 { $description "Literal syntax, consists of a C-type followed by a series of values terminated by " { $snippet "}" } }
21 { $notes "The appropriate specialized array vocabulary must be loaded; otherwise, an error will be thrown. See the " { $vocab-link "specialized-arrays" } " vocabulary for details on the underlying sequence type constructed." }
22 { $errors "Throws an error if the type does not exist, the necessary specialized array vocabulary is not loaded, or the requested size is negative." } ;
24 HELP: memory>byte-array
25 { $values { "alien" c-ptr } { "len" "a non-negative integer" } { "byte-array" byte-array } }
26 { $description "Reads " { $snippet "len" } " bytes starting from " { $snippet "base" } " and stores them in a new byte array." } ;
29 { $values { "byte-array" byte-array } { "c-type" "a C type" } { "array" "a specialized array" } }
30 { $description "Converts a byte array into a specialized array by interpreting the bytes in as machine-specific values. Code which uses this word is unportable" }
31 { $notes "The appropriate specialized array vocabulary must be loaded; otherwise, an error will be thrown. See the " { $vocab-link "specialized-arrays" } " vocabulary for details on the underlying sequence type constructed." }
32 { $errors "Throws an error if the type does not exist, the necessary specialized array vocabulary is not loaded, or the requested size is negative." } ;
35 { $values { "n" "a non-negative integer" } { "c-type" "a C type" } { "array" "a specialized array" } }
36 { $description "Allocates an unmanaged memory block large enough to hold " { $snippet "n" } " values of a C type, then wraps the memory in a sequence object using " { $link <c-direct-array> } "." }
37 { $notes "The appropriate specialized array vocabulary must be loaded; otherwise, an error will be thrown. See the " { $vocab-link "specialized-arrays" } " vocabulary for details on the underlying sequence type constructed." }
38 { $warning "Don't forget to deallocate the memory with a call to " { $link free } "." }
39 { $errors "Throws an error if the type does not exist, if the requested size is negative, if a direct specialized array class appropriate to the type is not loaded, or if memory allocation fails." } ;
41 HELP: malloc-byte-array
42 { $values { "byte-array" byte-array } { "alien" alien } }
43 { $description "Allocates an unmanaged memory block of the same size as the byte array, and copies the contents of the byte array there." }
44 { $warning "Don't forget to deallocate the memory with a call to " { $link free } "." }
45 { $errors "Throws an error if memory allocation fails." } ;
47 { <c-array> <c-direct-array> malloc-array } related-words
49 { string>alien alien>string malloc-string } related-words
51 HELP: with-scoped-allocation
52 { $values { "c-types" "a list of scoped allocation specifiers" } { "quot" quotation } }
53 { $description "Allocates values on the call stack, calls the quotation, then deallocates the values as soon as the quotation returns."
55 "A scoped allocation specifier is either:"
58 { "or a triple with shape " { $snippet "{ c-type initial: initial }" } ", where " { $snippet "c-type" } " is a C type name and " { $snippet "initial" } " is a literal value." }
60 "If no initial value is specified, the contents of the allocated memory are undefined." }
61 { $warning "Reading or writing a scoped allocation buffer outside of the given quotation will cause memory corruption." }
64 "USING: accessors alien.c-types alien.data
65 classes.struct kernel math math.functions
69 STRUCT: point { x int } { y int } ;
71 : scoped-allocation-test ( -- x )
74 [ x>> sq ] [ y>> sq ] bi + sqrt
75 ] with-scoped-allocation ;
77 scoped-allocation-test ."
82 HELP: with-out-parameters
83 { $values { "c-types" "a list of scoped allocation specifiers" } { "quot" quotation } { "values..." "zero or more values" } }
84 { $description "Allocates values on the call stack, calls the quotation, then copies all stack allocated values to the data heap after the quotation returns."
86 "A scoped allocation specifier is either:"
89 { "or a triple with shape " { $snippet "{ c-type initial: initial }" } ", where " { $snippet "c-type" } " is a C type name and " { $snippet "initial" } " is a literal value." }
91 "If no initial value is specified, the contents of the allocated memory are undefined." }
92 { $warning "Reading or writing a scoped allocation buffer outside of the given quotation will cause memory corruption." } ;
94 ARTICLE: "malloc" "Manual memory management"
95 "Sometimes data passed to C functions must be allocated at a fixed address. See " { $link "byte-arrays-gc" } " for an explanation of when this is the case."
97 "Allocating a C datum with a fixed address:"
101 "The " { $vocab-link "libc" } " vocabulary defines several words which directly call C standard library memory management functions:"
107 "You must always free pointers returned by any of the above words when the block of memory is no longer in use:"
108 { $subsections free }
109 "The above words record memory allocations, to help catch double frees and track down memory leaks with " { $link "tools.destructors" } ". To free memory allocated by a C library, another word can be used:"
110 { $subsections (free) }
111 "Utilities for automatically freeing memory in conjunction with " { $link with-destructors } ":"
116 "The " { $link &free } " and " { $link |free } " words are generated using " { $link "alien.destructors" } "."
118 "You can unsafely copy a range of bytes from one memory location to another:"
119 { $subsections memcpy }
120 "You can copy a range of bytes from memory into a byte array:"
121 { $subsections memory>byte-array } ;
123 ARTICLE: "c-pointers" "Passing pointers to C functions"
124 "The following Factor objects may be passed to C function parameters with pointer types:"
126 { "Instances of " { $link alien } "." }
127 { "Instances of " { $link f } "; this is interpreted as a null pointer." }
128 { "Instances of " { $link byte-array } "; the C function receives a pointer to the first element of the array." }
129 { "Any data type which defines a method on " { $link >c-ptr } ". This includes " { $link "classes.struct" } " and " { $link "specialized-arrays" } "." }
131 "The class of primitive C pointer types:"
132 { $subsections c-ptr }
133 "A generic word for converting any object to a C pointer; user-defined types may add methods to this generic word:"
134 { $subsections >c-ptr }
135 "More about the " { $link alien } " type:"
136 { $subsections "aliens" }
138 "The Factor garbage collector can move byte arrays around, and code passing byte arrays, or objects backed by byte arrays, must obey important guidelines. See " { $link "byte-arrays-gc" } "." } ;
140 ARTICLE: "c-boxes" "C value boxes"
141 "Sometimes it is useful to create a byte array storing a single C value, like a struct with a single field. A pair of utility macros exist to make this more convenient:"
142 { $subsections <ref> deref } ;
144 ARTICLE: "c-data" "Passing data between Factor and C"
145 "Two defining characteristics of Factor are dynamic typing and automatic memory management, which are somewhat incompatible with the machine-level data model exposed by C. Factor's C library interface defines its own set of C data types, distinct from Factor language types, together with automatic conversion between Factor values and C types. For example, C integer types must be declared and are fixed-width, whereas Factor supports arbitrary-precision integers."
147 "Furthermore, Factor's garbage collector can move objects in memory; for a discussion of the consequences, see " { $link "byte-arrays-gc" } "."
156 "Important guidelines for passing data in byte arrays:"
157 { $subsections "byte-arrays-gc" }
158 "C-style enumerated types are supported:"
159 { $subsections "alien.enums" }
160 "A utility for defining " { $link "destructors" } " for deallocating memory:"
161 { $subsections "alien.destructors" }
162 "C struct and union types can be defined with " { $link POSTPONE: STRUCT: } " and " { $link POSTPONE: UNION: } ". See " { $link "classes.struct" } " for details. For passing arrays to and from C, use the " { $link "specialized-arrays" } " vocabulary." ;
165 { $values { "string" string } { "encoding" "an encoding descriptor" } { "alien" c-ptr } }
166 { $description "Encodes a string together with a trailing null code point using the given encoding, and stores the resulting bytes in a freshly-allocated unmanaged memory block." }
167 { $warning "Don't forget to deallocate the memory with a call to " { $link free } "." }
168 { $errors "Throws an error if one of the following conditions occurs:"
170 "the string contains null code points"
171 "the string contains characters not representable using the encoding specified"
172 "memory allocation fails"
176 HELP: <c-direct-array>
177 { $values { "alien" c-ptr } { "len" integer } { "c-type" "a C type" } { "array" "a specialized direct array" } }
178 { $description "Constructs a new specialized array of length " { $snippet "len" } " and element type " { $snippet "c-type" } " over the range of memory referenced by " { $snippet "alien" } "." }
179 { $notes "The appropriate specialized array vocabulary must be loaded; otherwise, an error will be thrown. See the " { $vocab-link "specialized-arrays" } " vocabulary for details on the underlying sequence type constructed." } ;
181 ARTICLE: "c-strings" "C strings"
182 "C string types are arrays with shape " { $snippet "{ c-string encoding }" } ", where " { $snippet "encoding" } " is an encoding descriptor. The type " { $link c-string } " is an alias for " { $snippet "{ c-string utf8 }" } ". See " { $link "encodings-descriptors" } " for information about encoding descriptors. In " { $link POSTPONE: TYPEDEF: } ", " { $link POSTPONE: FUNCTION: } ", " { $link POSTPONE: CALLBACK: } ", and " { $link POSTPONE: STRUCT: } " definitions, the shorthand syntax " { $snippet "c-string[encoding]" } " can be used to specify the string encoding."
184 "Passing a Factor string to a C function expecting a " { $link c-string } " allocates a " { $link byte-array } " in the Factor heap; the string is then converted to the requested format and a raw pointer is passed to the function."
186 "If the conversion fails, for example if the string contains null bytes or characters with values higher than 255, a " { $link c-string-error. } " is thrown."
188 "Care must be taken if the C function expects a pointer to a string with its length represented by another parameter rather than a null terminator. Passing the result of calling " { $link length } " on the string object will not suffice. This is because a Factor string of " { $emphasis "n" } " characters will not necessarily encode to " { $emphasis "n" } " bytes. The correct idiom for C functions which take a string with a length is to first encode the string using " { $link encode } ", and then pass the resulting byte array together with the length of this byte array."
190 "Sometimes a C function has a parameter type of " { $link void* } ", and various data types, among them strings, can be passed in. In this case, strings are not automatically converted to aliens, and instead you must call one of these words:"
195 "The first allocates " { $link byte-array } "s, and the latter allocates manually-managed memory which is not moved by the garbage collector and has to be explicitly freed by calling " { $link free } ". See " { $link "byte-arrays-gc" } " for a discussion of the two approaches."
197 "The C type " { $snippet "char*" } " represents a generic pointer to " { $snippet "char" } "; arguments with this type will expect and return " { $link alien } "s, and won't perform any implicit string conversion."
199 "A word to read strings from arbitrary addresses:"
200 { $subsections alien>string }
201 "For example, if a C function returns a " { $link c-string } " but stipulates that the caller must deallocate the memory afterward, you must define the function as returning " { $snippet "char*" } " and call " { $link (free) } " yourself." ;
204 { $values { "value" object } { "c-type" "a C type" } { "c-ptr" c-ptr } }
205 { $description "Creates a new byte array to store a Factor object as a C value." }
207 { $example "USING: alien.c-types alien.data prettyprint sequences ;" "123 int <ref> length ." "4" }
211 { $values { "c-ptr" c-ptr } { "c-type" "a C type" } { "value" object } }
212 { $description "Loads a C value from a byte array." }
214 { $example "USING: alien.c-types alien.data prettyprint sequences ;" "321 int <ref> int deref ." "321" }
217 ARTICLE: "c-out-params" "Output parameters in C"
218 "A frequently-occurring idiom in C code is the \"out parameter\". If a C function returns more than one value, the caller passes pointers of the correct type, and the C function writes its return values to those locations."
219 { $subsection with-out-parameters } ;