basis/specialized-arrays/specialized-arrays-docs.factor

   1 USING: help.markup help.syntax byte-arrays alien ;
   2 IN: specialized-arrays
   3
   4 HELP: SPECIALIZED-ARRAY:
   5 { $syntax "SPECIALIZED-ARRAY: type" }
   6 { $values { "type" "a C type" } }
   7 { $description "Brings a specialized array for holding values of " { $snippet "type" } " into the vocabulary search path. The generated words are documented in " { $link "specialized-array-words" } "." } ;
   8
   9 HELP: SPECIALIZED-ARRAYS:
  10 { $syntax "SPECIALIZED-ARRAYS: type type type ... ;" }
  11 { $values { "type" "a C type" } }
  12 { $description "Brings a set of specialized arrays for holding values of each " { $snippet "type" } " into the vocabulary search path. The generated words are documented in " { $link "specialized-array-words" } "." } ;
  13
  14 { POSTPONE: SPECIALIZED-ARRAY: POSTPONE: SPECIALIZED-ARRAYS: } related-words
  15
  16 ARTICLE: "specialized-array-words" "Specialized array words"
  17 "The " { $link POSTPONE: SPECIALIZED-ARRAY: } " and " { $link POSTPONE: SPECIALIZED-ARRAYS: } " parsing words generate specialized array types if they haven't been generated already and add the following words to the vocabulary search path, where " { $snippet "T" } " is the C type in question:"
  18 { $table
  19     { { $snippet "T-array" } { "The class of arrays with elements of type " { $snippet "T" } } }
  20     { { $snippet "<T-array>" } { "Constructor for arrays with elements of type " { $snippet "T" } "; stack effect " { $snippet "( len -- array )" } } }
  21     { { $snippet "(T-array)" } { "Constructor for arrays with elements of type " { $snippet "T" } ", where the initial contents are uninitialized; stack effect " { $snippet "( len -- array )" } } }
  22     { { $snippet "malloc-T-array" } { "Constructor for arrays with elements of type " { $snippet "T" } " backed by newly-allocated unmanaged memory; stack effect " { $snippet "( alien len -- array )" } } }
  23     { { $snippet "<direct-T-array>" } { "Constructor for arrays with elements of type " { $snippet "T" } " backed by raw memory; stack effect " { $snippet "( alien len -- array )" } } }
  24     { { $snippet "byte-array>T-array" } { "Converts a byte array into a specialized array by interpreting the bytes in as machine-specific values. Code which uses this word is unportable" } }
  25     { { $snippet ">T-array" } { "Converts a sequence into a specialized array of type " { $snippet "T" } "; stack effect " { $snippet "( seq -- array )" } } }
  26     { { $snippet "T-array{" } { "Literal syntax, consists of a series of values terminated by " { $snippet "}" } } }
  27 }
  28 "Behind the scenes, these words are placed in a vocabulary named " { $snippet "specialized-arrays.instances.T" } ", however this vocabulary should not be placed in a " { $link POSTPONE: USING: } " form directly. Instead, always use " { $link POSTPONE: SPECIALIZED-ARRAY: } " or " { $link POSTPONE: SPECIALIZED-ARRAYS: } ". This ensures that the vocabulary can get generated the first time it is needed." ;
  29
  30 ARTICLE: "specialized-array-c" "Passing specialized arrays to C functions"
  31 "If a C function is declared as taking a parameter with a pointer or an array type (for example, " { $snippet "float*" } " or " { $snippet "int[3]" } "), instances of the relevant specialized array can be passed in."
  32 $nl
  33 "C type specifiers for array types are documented in " { $link "c-types-specs" } "."
  34 $nl
  35 "Here is an example; as is common with C functions, the array length is passed in separately, since C does not offer a runtime facility to determine the array length of a base pointer:"
  36 { $code
  37     "USING: alien.syntax specialized-arrays ;"
  38     "SPECIALIZED-ARRAY: int"
  39     "FUNCTION: void process_data ( int* data, int len ) ;"
  40     "int-array{ 10 20 30 } dup length process_data"
  41 }
  42 "Literal specialized arrays, as well as specialized arrays created with " { $snippet "<T-array>" } " and " { $snippet ">T-array" } " are backed by a " { $link byte-array } " in the Factor heap, and can move as a result of garbage collection. If this is unsuitable, the array can be allocated in unmanaged memory instead."
  43 $nl
  44 "In the following example, it is presumed that the C library holds on to a pointer to the array's data after the " { $snippet "init_with_data()" } " call returns; this is one situation where unmanaged memory has to be used instead. Note the use of destructors to ensure the memory is deallocated after the block ends:"
  45 { $code
  46     "USING: alien.syntax specialized-arrays ;"
  47     "SPECIALIZED-ARRAY: float"
  48     "FUNCTION: void init_with_data ( float* data, int len ) ;"
  49     "FUNCTION: float compute_result ( ) ;"
  50     "["
  51     "    100 malloc-float-array &free"
  52     "    dup length init_with_data"
  53     "    compute_result"
  54     "] with-destructors"
  55 }
  56 "Finally, sometimes a C library returns a pointer to an array in unmanaged memory, together with a length. In this case, a specialized array can be constructed to view this memory using " { $snippet "<direct-T-array>" } ":"
  57 { $code
  58     "USING: alien.c-types classes.struct ;"
  59     ""
  60     "STRUCT: device_info"
  61     "    { id int }"
  62     "    { name char* } ;"
  63     ""
  64     "FUNCTION: void get_device_info ( int* length ) ;"
  65     ""
  66     "0 <int> [ get_device_info ] keep <direct-int-array> ."
  67 }
  68 "For a full discussion of Factor heap allocation versus unmanaged memory allocation, see " { $link "byte-arrays-gc" } "."
  69 $nl
  70 "Each specialized array has a " { $slot "underlying" } " slot holding a " { $link byte-array } " with the raw data. Passing a specialized array as a parameter to a C function call will automatically extract the underlying data. To get at the underlying data directly, call the " { $link >c-ptr } " word on a specialized array." ;
  71
  72 ARTICLE: "specialized-array-math" "Vector arithmetic with specialized arrays"
  73 "Each specialized array with a numeric type generates specialized versions of the " { $link "math-vectors" } " words. The compiler substitutes calls for these words if it can statically determine input types. The " { $snippet "optimized." } " word in the " { $vocab-link "compiler.tree.debugger" } " vocabulary can be used to determine if this optimization is being performed for a particular piece of code." ;
  74
  75 ARTICLE: "specialized-array-examples" "Specialized array examples"
  76 "Let's import specialized float arrays:"
  77 { $code "USING: specialized-arrays math.constants math.functions ;" "SPECIALIZED-ARRAY: float" }
  78 "Creating a float array with 3 elements:"
  79 { $code "1.0 [ sin ] [ cos ] [ tan ] tri float-array{ } 3sequence ." }
  80 "Create a float array and sum the elements:"
  81 { $code
  82     "1000 iota [ 1000 /f pi * sin ] float-array{ } map-as"
  83     "0.0 [ + ] reduce ."
  84 } ;
  85
  86 ARTICLE: "specialized-arrays" "Specialized arrays"
  87 "The " { $vocab-link "specialized-arrays" } " vocabulary implements fixed-length sequence types for storing machine values in a space-efficient manner without boxing."
  88 $nl
  89 "A specialized array type needs to be generated for each element type. This is done with parsing words:"
  90 { $subsections
  91     POSTPONE: SPECIALIZED-ARRAY:
  92     POSTPONE: SPECIALIZED-ARRAYS:
  93 }
  94 "This parsing word adds new words to the search path, documented in the next section."
  95 { $subsections
  96     "specialized-array-words"
  97     "specialized-array-c"
  98     "specialized-array-math"
  99     "specialized-array-examples"
 100 }
 101 "The " { $vocab-link "specialized-vectors" } " vocabulary provides a resizable version of this abstraction." ;
 102
 103 ABOUT: "specialized-arrays"