basis/stack-checker/alien/alien-docs.factor

   1 USING: alien alien.c-types compiler.tree help.markup help.syntax
   2 quotations sequences ;
   3 IN: stack-checker.alien
   4
   5 HELP: alien-node-params
   6 { $class-description "Base class for the parameter slot of " { $link #alien-node } " nodes. It has the following slots:"
   7   { $slots
   8     { "return" { "a " { $link c-type-name } " which indicates the type of the functions return value." } }
   9     { "parameters" { "a " { $link sequence } " of " { $link c-type-name } " giving the types of the functions parameters." } }
  10     { "abi" { "calling convention of the function the node parameters operates on." } }
  11   }
  12 }
  13 { $see-also abi } ;
  14
  15 HELP: alien-callback-params
  16 { $class-description "Class that holds the parameter types and return value type of an alien callback call." }
  17 { $see-also #alien-callback } ;
  18
  19 HELP: param-prep-quot
  20 { $values { "params" alien-node-params } { "quot" quotation } }
  21 { $description "Builds a quotation which coerces values on the stack to the required types for the alien call." }
  22 { $examples
  23   { $unchecked-example
  24     "USING: alien.c-types prettyprint stack-checker.alien ;"
  25     "T{ alien-invoke-params { parameters { void* c-string int } } } param-prep-quot ."
  26     "[ [ [ [ ] dip >c-ptr ] dip \\ utf8 string>alien ] dip >fixnum ]"
  27   }
  28 } ;
  29
  30 HELP: callback-parameter-quot
  31 { $values { "params" alien-node-params } { "quot" quotation } }
  32 { $description "Builds a quotation which coerces values on the stack to the required types for an alien callback. This word is essentially the opposite to " { $link param-prep-quot } "." }
  33 { $examples
  34   { $unchecked-example
  35     "USING: alien.c-types prettyprint stack-checker.alien ;"
  36     "T{ alien-node-params { parameters { c-string } } } callback-parameter-quot ."
  37     "[ { object } declare [ ] dip \ utf8 alien>string ]"
  38   }
  39 } ;
  40
  41 HELP: infer-alien-assembly
  42 { $description "Infers " { $link alien-assembly } " calls." } ;
  43
  44 HELP: infer-alien-invoke
  45 { $description "Appends the necessary SSA nodes for performing an " { $link alien-invoke } " call to the IR tree being constructed." } ;
  46
  47 HELP: wrap-callback-quot
  48 { $values { "params" alien-node-params } { "quot" quotation } { "quot'" quotation } }
  49 { $description "Wraps the given quotation in protective packaging so that it becomes suitable to be used as an alien callback. That means that the parameters are unpacked from C types to Factor types and, if the callback returns something, the top data stack item is afterwards converted to a C compatible value." }
  50 { $examples
  51   "Here a callback that returns the length of a " { $link c-string } " is wrapped:"
  52   { $unchecked-example
  53     "USING: alien.c-types prettyprint stack-checker.alien ;"
  54     "T{ alien-node-params { return int } { parameters { c-string } } } "
  55     "[ length ] wrap-callback-quot ."
  56     "["
  57     "   ["
  58     "       { object } declare [ ] dip \ utf8 alien>string"
  59     "       length >fixnum"
  60     "   ] ["
  61     "       dup current-callback eq?"
  62     "       [ drop ] [ wait-for-callback ] if"
  63     "   ] do-callback"
  64     "]"
  65   }
  66 } ;
  67
  68 ARTICLE: "stack-checker.alien" "Inferring alien words" "This vocab contains code for inferring the words that form part of the alien FFI: " { $link alien-invoke } ", " { $link alien-indirect } ", " { $link alien-assembly } " and " { $link alien-callback } ". The words performing the inferring are:"
  69 { $subsections
  70   infer-alien-invoke
  71   infer-alien-indirect
  72   infer-alien-assembly
  73   infer-alien-callback
  74 } ;
  75
  76 ABOUT: "stack-checker.alien"