From 818bbb4984e556fbdb7f46a6a5a2d42e704ac904 Mon Sep 17 00:00:00 2001 From: Joe Groff Date: Tue, 23 Feb 2010 11:03:48 -0800 Subject: [PATCH] update docs about pointer types --- basis/alien/c-types/c-types-docs.factor | 21 +++++++++++++++++---- basis/alien/syntax/syntax-docs.factor | 8 ++++---- core/alien/alien-docs.factor | 4 ++-- 3 files changed, 23 insertions(+), 10 deletions(-) diff --git a/basis/alien/c-types/c-types-docs.factor b/basis/alien/c-types/c-types-docs.factor index 215ca1b0ef..f0a339b1aa 100644 --- a/basis/alien/c-types/c-types-docs.factor +++ b/basis/alien/c-types/c-types-docs.factor @@ -103,7 +103,7 @@ HELP: ulonglong HELP: void { $description "This symbol is not a valid C type, but it can be used as the return type for a " { $link POSTPONE: FUNCTION: } " or " { $link POSTPONE: CALLBACK: } " definition or for an " { $link alien-invoke } " or " { $link alien-callback } " call." } ; HELP: void* -{ $description "This C type represents a pointer to C memory. " { $link byte-array } " and " { $link alien } " values can be passed as " { $snippet "void*" } " function inputs, but see " { $link "byte-arrays-gc" } " for notes about passing byte arrays into C functions. " { $snippet "void*" } " output values are returned as " { $link alien } "s." } ; +{ $description "This C type represents a generic pointer to C memory. See " { $link pointer } " for information on pointer C types." } HELP: char* { $description "This C type represents a pointer to a C string. See " { $link "c-strings" } " for details about using strings with the FFI." } ; HELP: float @@ -115,6 +115,19 @@ HELP: complex-float HELP: complex-double { $description "This C type represents a double-precision IEEE 754 floating-point complex type. Input values will be converted from Factor " { $link math:complex } " objects into a double-precision complex float type; output values will be returned as Factor " { $link math:complex } " objects." } ; +HELP: pointer: +{ $syntax "pointer: c-type" } +{ $description "Constructs a " { $link pointer } " C type." } ; + +HELP: pointer +{ $class-description "Represents a pointer C type. The " { $snippet "to" } " slot contains the C type being pointed to." { $link byte-array } " and " { $link alien } " values can be provided as pointer function inputs, but see " { $link "byte-arrays-gc" } " for notes about passing byte arrays into C functions. Objects with methods on " { $link >c-ptr } ", such as structs and specialized arrays, may also be used as pointer inputs." +$nl +"Pointer output values are represented in Factor as " { $link alien } "s. If the pointed-to type is a struct, the alien will automatically be wrapped in a struct object if it is not null." +$nl +"In " { $link POSTPONE: TYPEDEF: } ", " { $link POSTPONE: FUNCTION: } ", " { $link POSTPONE: CALLBACK: } ", and " { $link POSTPONE: STRUCT: } " definitions, pointer types can be created by suffixing " { $snippet "*" } " to a C type name. Outside of FFI definitions, a pointer C type can be created using the " { $link POSTPONE: pointer: } " syntax word:" +{ $unchecked-example "FUNCTION: int* foo ( char* bar ) ;" } +{ $unchecked-example """: foo ( bar -- int* ) + pointer: int f \"foo\" { pointer: char } alien-invoke ;""" } } ; ARTICLE: "byte-arrays-gc" "Byte arrays and the garbage collector" "The Factor garbage collector can move byte arrays around, and it is only safe to pass byte arrays to C functions if the garbage collector will not run while C code still has a reference to the data." @@ -191,11 +204,11 @@ ARTICLE: "c-types.primitives" "Primitive C types" "When making alien calls, Factor numbers are converted to and from the above types in a canonical way. Converting a Factor number to a C value may result in a loss of precision." ; ARTICLE: "c-types.pointers" "Pointer and array types" -"Pointer types are specified by suffixing a C type with " { $snippet "*" } ", for example " { $snippet "float*" } ". One special case is " { $link void* } ", which denotes a generic pointer; " { $link void } " by itself is not a valid C type specifier. With the exception of strings (see " { $link "c-strings" } "), all pointer types are identical to " { $snippet "void*" } " as far as the C library interface is concerned." +"Pointer types are specified by suffixing a C type with " { $snippet "*" } ", for example " { $snippet "float*" } ". One special case is " { $link void* } ", which denotes a generic pointer; " { $link void } " by itself is not a valid C type specifier. This syntax constructs a " { $link pointer } " object to represent the C type." $nl "Fixed-size array types are supported; the syntax consists of a C type name followed by dimension sizes in brackets; the following denotes a 3 by 4 array of integers:" { $code "int[3][4]" } -"Fixed-size arrays differ from pointers in that they are allocated inside structures and unions; however when used as function parameters they behave exactly like pointers and thus the dimensions only serve as documentation." ; +"Fixed-size arrays differ from pointers in that they are allocated inside structures and unions; however, when used as function parameters, they behave exactly like pointers with the dimensions only serving as documentation." ; ARTICLE: "c-types.ambiguity" "Word name clashes with C types" "Note that some of the C type word names clash with commonly-used Factor words:" @@ -228,7 +241,7 @@ ARTICLE: "c-types.structs" "Struct and union types" "Struct and union types are identified by their class word. See " { $link "classes.struct" } "." ; ARTICLE: "c-types-specs" "C type specifiers" -"C types are identified by special words, and type names occur as parameters to the " { $link alien-invoke } ", " { $link alien-indirect } " and " { $link alien-callback } " words." +"C types are identified by special words. Type names occur as parameters to the " { $link alien-invoke } ", " { $link alien-indirect } " and " { $link alien-callback } " words." $nl "Defining new C types:" { $subsections diff --git a/basis/alien/syntax/syntax-docs.factor b/basis/alien/syntax/syntax-docs.factor index a8d3048b82..8ec67d2f65 100644 --- a/basis/alien/syntax/syntax-docs.factor +++ b/basis/alien/syntax/syntax-docs.factor @@ -54,7 +54,7 @@ $nl HELP: TYPEDEF: { $syntax "TYPEDEF: old new" } { $values { "old" "a C type" } { "new" "a C type" } } -{ $description "Aliases the C type " { $snippet "old" } " under the name " { $snippet "new" } " if ." } +{ $description "Aliases the C type " { $snippet "old" } " under the name " { $snippet "new" } "." } { $notes "This word differs from " { $link typedef } " in that it runs at parse time, to ensure correct ordering of operations when loading source files. Words defined in source files are compiled before top-level forms are run, so if a source file defines C binding words and uses " { $link typedef } ", the type alias won't be available at compile time." } ; HELP: C-ENUM: @@ -72,12 +72,12 @@ HELP: C-ENUM: HELP: C-TYPE: { $syntax "C-TYPE: type" } { $values { "type" "a new C type" } } -{ $description "Defines a new, opaque C type. Since it is opaque, " { $snippet "type" } " will not be directly usable as a parameter or return type of a " { $link POSTPONE: FUNCTION: } " or as a slot of a " { $link POSTPONE: STRUCT: } ". However, it can be used as the type of a pointer (that is, as " { $snippet "type*" } ")." $nl -{ $snippet "C-TYPE:" } " can also be used to forward-declare C types to enable circular dependencies. For example:" +{ $description "Defines a new, opaque C type. Since it is opaque, " { $snippet "type" } " will not be directly usable as a parameter or return type of a " { $link POSTPONE: FUNCTION: } " or as a slot of a " { $link POSTPONE: STRUCT: } ". However, it can be used as the type of a " { $link pointer } "." +{ $snippet "C-TYPE:" } " can also be used to forward declare C types, allowing circular dependencies to occur between types. For example:" { $code """C-TYPE: forward STRUCT: backward { x forward* } ; STRUCT: forward { x backward* } ; """ } } -{ $notes "Primitive C types are also displayed using " { $snippet "C-TYPE:" } " syntax when they are displayed by " { $link see } "." } ; +{ $notes "Primitive C types are displayed using " { $snippet "C-TYPE:" } " syntax when they are " { $link see } "n." } ; HELP: CALLBACK: { $syntax "CALLBACK: return type ( parameters ) ;" } diff --git a/core/alien/alien-docs.factor b/core/alien/alien-docs.factor index 98292b8728..0b4976fcbe 100644 --- a/core/alien/alien-docs.factor +++ b/core/alien/alien-docs.factor @@ -42,7 +42,7 @@ HELP: { $notes "Alien objects are invalidated between image saves and loads." } ; HELP: c-ptr -{ $class-description "Class of objects consisting of aliens, byte arrays and " { $link f } ". These objects can convert to pointer C types, which are all aliases of " { $snippet "void*" } "." } ; +{ $class-description "Class of objects consisting of aliens, byte arrays and " { $link f } ". These objects all can be used as values of " { $link pointer } " C types." } ; HELP: alien-invoke-error { $error-description "Thrown if the word calling " { $link alien-invoke } " was not compiled with the optimizing compiler. This may be a result of one of several failure conditions:" @@ -136,7 +136,7 @@ ARTICLE: "aliens" "Alien addresses" } "Anywhere that a " { $link alien } " instance is accepted, the " { $link f } " singleton may be passed in to denote a null pointer." $nl -"Usually alien objects do not have to created and dereferenced directly; instead declaring C function parameters and return values as having a pointer type such as " { $snippet "void*" } " takes care of the details." +"Usually alien objects do not have to created and dereferenced directly; instead declaring C function parameters and return values as having a " pointer type such as " { $snippet "void*" } " takes care of the details." { $subsections "syntax-aliens" "alien-expiry" -- 2.34.1