unmaintained/alien/marshall/marshall-docs.factor

   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 ;
   5 IN: alien.marshall
   6
   7 <PRIVATE
   8 : $memory-note ( arg -- )
   9     drop "This word returns a pointer to unmanaged memory."
  10     print-element ;
  11
  12 : $c-ptr-note ( arg -- )
  13     drop "Does nothing if its argument is a non false c-ptr."
  14     print-element ;
  15
  16 : $see-article ( arg -- )
  17     drop { "See " { $vocab-link "alien.inline" } "." }
  18     print-element ;
  19 PRIVATE>
  20
  21 HELP: ?malloc-byte-array
  22 { $values
  23     { "c-type" c-type }
  24     { "alien" alien }
  25 }
  26 { $description "Does nothing if input is an alien, otherwise assumes it is a byte array and calls "
  27   { $snippet "malloc-byte-array" } "."
  28 }
  29 { $notes $memory-note } ;
  30
  31 HELP: alien-wrapper
  32 { $var-description "For wrapping C pointers in a structure factor can dispatch on." } ;
  33
  34 HELP: unmarshall-cast
  35 { $values
  36     { "alien-wrapper" alien-wrapper }
  37     { "alien-wrapper'" alien-wrapper }
  38 }
  39 { $description "Called immediately after unmarshalling. Useful for automatically casting to subtypes." } ;
  40
  41 HELP: marshall-bool
  42 { $values
  43     { "?" "a generalized boolean" }
  44     { "n" "0 or 1" }
  45 }
  46 { $description "Marshalls objects to bool." }
  47 { $notes "Will treat " { $snippet "0" } " as " { $snippet "t" } "." } ;
  48
  49 HELP: marshall-bool*
  50 { $values
  51     { "?/seq" "t/f or sequence" }
  52     { "alien" alien }
  53 }
  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."
  56 }
  57 { $notes { $list $c-ptr-note $memory-note } } ;
  58
  59 HELP: marshall-bool**
  60 { $values
  61     { "seq" sequence }
  62     { "alien" alien }
  63 }
  64 { $description "Takes a one or two dimensional array of generalized booleans "
  65   "and returns a pointer to the equivalent C structure."
  66 }
  67 { $notes { $list $c-ptr-note $memory-note } } ;
  68
  69 HELP: marshall-primitive
  70 { $values
  71     { "n" number }
  72     { "n" number }
  73 }
  74 { $description "Marshall numbers to C primitives."
  75     $nl
  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."
  80 } ;
  81
  82 HELP: marshall-char*
  83 { $values
  84     { "n/seq" "number or sequence" }
  85     { "alien" alien }
  86 }
  87 { $description $see-article }
  88 { $notes { $list $c-ptr-note $memory-note } } ;
  89
  90 HELP: marshall-char**
  91 { $values
  92     { "seq" sequence }
  93     { "alien" alien }
  94 }
  95 { $description $see-article }
  96 { $notes { $list $c-ptr-note $memory-note } } ;
  97
  98 HELP: marshall-char**-or-strings
  99 { $values
 100     { "seq" "a sequence of strings" }
 101     { "alien" alien }
 102 }
 103 { $description "Marshalls an array of strings or characters to an array of C strings." }
 104 { $notes { $list $c-ptr-note $memory-note } } ;
 105
 106 HELP: marshall-char*-or-string
 107 { $values
 108     { "n/string" "a number or string" }
 109     { "alien" alien }
 110 }
 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 } } ;
 113
 114 HELP: marshall-double*
 115 { $values
 116     { "n/seq" "a number or sequence" }
 117     { "alien" alien }
 118 }
 119 { $description $see-article }
 120 { $notes { $list $c-ptr-note $memory-note } } ;
 121
 122 HELP: marshall-double**
 123 { $values
 124     { "seq" sequence }
 125     { "alien" alien }
 126 }
 127 { $description $see-article }
 128 { $notes { $list $c-ptr-note $memory-note } } ;
 129
 130 HELP: marshall-float*
 131 { $values
 132     { "n/seq" "a number or sequence" }
 133     { "alien" alien }
 134 }
 135 { $description $see-article }
 136 { $notes { $list $c-ptr-note $memory-note } } ;
 137
 138 HELP: marshall-float**
 139 { $values
 140     { "seq" sequence }
 141     { "alien" alien }
 142 }
 143 { $description $see-article }
 144 { $notes { $list $c-ptr-note $memory-note } } ;
 145
 146 HELP: marshall-int*
 147 { $values
 148     { "n/seq" "a number or sequence" }
 149     { "alien" alien }
 150 }
 151 { $description $see-article }
 152 { $notes { $list $c-ptr-note $memory-note } } ;
 153
 154 HELP: marshall-int**
 155 { $values
 156     { "seq" sequence }
 157     { "alien" alien }
 158 }
 159 { $description $see-article }
 160 { $notes { $list $c-ptr-note $memory-note } } ;
 161
 162 HELP: marshall-long*
 163 { $values
 164     { "n/seq" "a number or sequence" }
 165     { "alien" alien }
 166 }
 167 { $description $see-article }
 168 { $notes { $list $c-ptr-note $memory-note } } ;
 169
 170 HELP: marshall-long**
 171 { $values
 172     { "seq" sequence }
 173     { "alien" alien }
 174 }
 175 { $description $see-article }
 176 { $notes { $list $c-ptr-note $memory-note } } ;
 177
 178 HELP: marshall-longlong*
 179 { $values
 180     { "n/seq" "a number or sequence" }
 181     { "alien" alien }
 182 }
 183 { $description $see-article }
 184 { $notes { $list $c-ptr-note $memory-note } } ;
 185
 186 HELP: marshall-longlong**
 187 { $values
 188     { "seq" sequence }
 189     { "alien" alien }
 190 }
 191 { $description $see-article }
 192 { $notes { $list $c-ptr-note $memory-note } } ;
 193
 194 HELP: marshall-non-pointer
 195 { $values
 196     { "alien-wrapper/byte-array" "an alien-wrapper or byte-array" }
 197     { "byte-array" byte-array }
 198 }
 199 { $description "Converts argument to a byte array." }
 200 { $notes "Not meant to be called directly. Use the output of " { $link marshaller } " instead." } ;
 201
 202 HELP: marshall-pointer
 203 { $values
 204     { "obj" object }
 205     { "alien" alien }
 206 }
 207 { $description "Converts argument to a C pointer." }
 208 { $notes "Can marshall the following types: " { $snippet "alien, f, byte-array, alien-wrapper, struct-array" } "." } ;
 209
 210 HELP: marshall-short*
 211 { $values
 212     { "n/seq" "a number or sequence" }
 213     { "alien" alien }
 214 }
 215 { $description $see-article }
 216 { $notes { $list $c-ptr-note $memory-note } } ;
 217
 218 HELP: marshall-short**
 219 { $values
 220     { "seq" sequence }
 221     { "alien" alien }
 222 }
 223 { $description $see-article }
 224 { $notes { $list $c-ptr-note $memory-note } } ;
 225
 226 HELP: marshall-uchar*
 227 { $values
 228     { "n/seq" "a number or sequence" }
 229     { "alien" alien }
 230 }
 231 { $description $see-article }
 232 { $notes { $list $c-ptr-note $memory-note } } ;
 233
 234 HELP: marshall-uchar**
 235 { $values
 236     { "seq" sequence }
 237     { "alien" alien }
 238 }
 239 { $description $see-article }
 240 { $notes { $list $c-ptr-note $memory-note } } ;
 241
 242 HELP: marshall-uint*
 243 { $values
 244     { "n/seq" "a number or sequence" }
 245     { "alien" alien }
 246 }
 247 { $description $see-article }
 248 { $notes { $list $c-ptr-note $memory-note } } ;
 249
 250 HELP: marshall-uint**
 251 { $values
 252     { "seq" sequence }
 253     { "alien" alien }
 254 }
 255 { $description $see-article }
 256 { $notes { $list $c-ptr-note $memory-note } } ;
 257
 258 HELP: marshall-ulong*
 259 { $values
 260     { "n/seq" "a number or sequence" }
 261     { "alien" alien }
 262 }
 263 { $description $see-article }
 264 { $notes { $list $c-ptr-note $memory-note } } ;
 265
 266 HELP: marshall-ulong**
 267 { $values
 268     { "seq" sequence }
 269     { "alien" alien }
 270 }
 271 { $description $see-article }
 272 { $notes { $list $c-ptr-note $memory-note } } ;
 273
 274 HELP: marshall-ulonglong*
 275 { $values
 276     { "n/seq" "a number or sequence" }
 277     { "alien" alien }
 278 }
 279 { $description $see-article }
 280 { $notes { $list $c-ptr-note $memory-note } } ;
 281
 282 HELP: marshall-ulonglong**
 283 { $values
 284     { "seq" sequence }
 285     { "alien" alien }
 286 }
 287 { $description $see-article }
 288 { $notes { $list $c-ptr-note $memory-note } } ;
 289
 290 HELP: marshall-ushort*
 291 { $values
 292     { "n/seq" "a number or sequence" }
 293     { "alien" alien }
 294 }
 295 { $description $see-article }
 296 { $notes { $list $c-ptr-note $memory-note } } ;
 297
 298 HELP: marshall-ushort**
 299 { $values
 300     { "seq" sequence }
 301     { "alien" alien }
 302 }
 303 { $description $see-article }
 304 { $notes { $list $c-ptr-note $memory-note } } ;
 305
 306 HELP: marshall-void**
 307 { $values
 308     { "seq" sequence }
 309     { "alien" alien }
 310 }
 311 { $description "Marshalls a sequence of objects to an array of pointers to void." }
 312 { $notes { $list $c-ptr-note $memory-note } } ;
 313
 314 HELP: marshaller
 315 { $values
 316     { "type" "a C type string" }
 317     { "quot" quotation }
 318 }
 319 { $description "Given a C type, returns a quotation that will marshall its argument to that type." } ;
 320
 321 HELP: out-arg-unmarshaller
 322 { $values
 323     { "type" "a C type string" }
 324     { "quot" quotation }
 325 }
 326 { $description "Like " { $link unmarshaller } " but returns an empty quotation "
 327     "for all types except pointers to non-const primitives."
 328 } ;
 329
 330 HELP: class-unmarshaller
 331 { $values
 332     { "type" " a C type string" }
 333     { "quot/f" quotation }
 334 }
 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."
 338 }
 339 { $notes "Not meant to be called directly. Use the output of " { $link marshaller } " instead." } ;
 340
 341 HELP: primitive-marshaller
 342 { $values
 343     { "type" "a C type string" }
 344     { "quot/f" "a quotation or f" }
 345 }
 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." } ;
 348
 349 HELP: primitive-unmarshaller
 350 { $values
 351     { "type" "a C type string" }
 352     { "quot/f" "a quotation or f" }
 353 }
 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." } ;
 356
 357 HELP: struct-field-unmarshaller
 358 { $values
 359     { "type" "a C type string" }
 360     { "quot" quotation }
 361 }
 362 { $description "Like " { $link unmarshaller } " but returns a quotation that "
 363     "does not call " { $snippet "free" } " on its argument."
 364 }
 365 { $notes "Not meant to be called directly. Use the output of " { $link unmarshaller } " instead." } ;
 366
 367 HELP: struct-primitive-unmarshaller
 368 { $values
 369     { "type" "a C type string" }
 370     { "quot/f" "a quotation or f" }
 371 }
 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." } ;
 375
 376 HELP: struct-unmarshaller
 377 { $values
 378     { "type" "a C type string" }
 379     { "quot/f" quotation }
 380 }
 381 { $description "Returns a quotation which wraps its argument in the subclass of "
 382     { $link struct-wrapper } " which matches the " { $snippet "type" } " arg."
 383 }
 384 { $notes "Not meant to be called directly. Use the output of " { $link unmarshaller } " instead." } ;
 385
 386 HELP: struct-wrapper
 387 { $var-description "For wrapping C structs in a structure factor can dispatch on." } ;
 388
 389 HELP: unmarshall-bool
 390 { $values
 391     { "n" number }
 392     { "?" boolean }
 393 }
 394 { $description "Unmarshalls a number to a boolean." } ;
 395
 396 HELP: unmarshall-bool*
 397 { $values
 398     { "alien" alien }
 399     { "?" boolean }
 400 }
 401 { $description "Unmarshalls a C pointer to a boolean." } ;
 402
 403 HELP: unmarshall-bool*-free
 404 { $values
 405     { "alien" alien }
 406     { "?" boolean }
 407 }
 408 { $description "Unmarshalls a C pointer to a boolean and frees the pointer." } ;
 409
 410 HELP: unmarshall-char*
 411 { $values
 412     { "alien" alien }
 413     { "n" number }
 414 }
 415 { $description $see-article } ;
 416
 417 HELP: unmarshall-char*-free
 418 { $values
 419     { "alien" alien }
 420     { "n" number }
 421 }
 422 { $description $see-article } ;
 423
 424 HELP: unmarshall-char*-to-string
 425 { $values
 426     { "alien" alien }
 427     { "string" string }
 428 }
 429 { $description "Unmarshalls a " { $snippet "char" } " pointer to a factor string." } ;
 430
 431 HELP: unmarshall-char*-to-string-free
 432 { $values
 433     { "alien" alien }
 434     { "string" string }
 435 }
 436 { $description "Unmarshalls a " { $snippet "char" } " pointer to a factor string and frees the pointer." } ;
 437
 438 HELP: unmarshall-double*
 439 { $values
 440     { "alien" alien }
 441     { "n" number }
 442 }
 443 { $description $see-article } ;
 444
 445 HELP: unmarshall-double*-free
 446 { $values
 447     { "alien" alien }
 448     { "n" number }
 449 }
 450 { $description $see-article } ;
 451
 452 HELP: unmarshall-float*
 453 { $values
 454     { "alien" alien }
 455     { "n" number }
 456 }
 457 { $description $see-article } ;
 458
 459 HELP: unmarshall-float*-free
 460 { $values
 461     { "alien" alien }
 462     { "n" number }
 463 }
 464 { $description $see-article } ;
 465
 466 HELP: unmarshall-int*
 467 { $values
 468     { "alien" alien }
 469     { "n" number }
 470 }
 471 { $description $see-article } ;
 472
 473 HELP: unmarshall-int*-free
 474 { $values
 475     { "alien" alien }
 476     { "n" number }
 477 }
 478 { $description $see-article } ;
 479
 480 HELP: unmarshall-long*
 481 { $values
 482     { "alien" alien }
 483     { "n" number }
 484 }
 485 { $description $see-article } ;
 486
 487 HELP: unmarshall-long*-free
 488 { $values
 489     { "alien" alien }
 490     { "n" number }
 491 }
 492 { $description $see-article } ;
 493
 494 HELP: unmarshall-longlong*
 495 { $values
 496     { "alien" alien }
 497     { "n" number }
 498 }
 499 { $description $see-article } ;
 500
 501 HELP: unmarshall-longlong*-free
 502 { $values
 503     { "alien" alien }
 504     { "n" number }
 505 }
 506 { $description $see-article } ;
 507
 508 HELP: unmarshall-short*
 509 { $values
 510     { "alien" alien }
 511     { "n" number }
 512 }
 513 { $description $see-article } ;
 514
 515 HELP: unmarshall-short*-free
 516 { $values
 517     { "alien" alien }
 518     { "n" number }
 519 }
 520 { $description $see-article } ;
 521
 522 HELP: unmarshall-uchar*
 523 { $values
 524     { "alien" alien }
 525     { "n" number }
 526 }
 527 { $description $see-article } ;
 528
 529 HELP: unmarshall-uchar*-free
 530 { $values
 531     { "alien" alien }
 532     { "n" number }
 533 }
 534 { $description $see-article } ;
 535
 536 HELP: unmarshall-uint*
 537 { $values
 538     { "alien" alien }
 539     { "n" number }
 540 }
 541 { $description $see-article } ;
 542
 543 HELP: unmarshall-uint*-free
 544 { $values
 545     { "alien" alien }
 546     { "n" number }
 547 }
 548 { $description $see-article } ;
 549
 550 HELP: unmarshall-ulong*
 551 { $values
 552     { "alien" alien }
 553     { "n" number }
 554 }
 555 { $description $see-article } ;
 556
 557 HELP: unmarshall-ulong*-free
 558 { $values
 559     { "alien" alien }
 560     { "n" number }
 561 }
 562 { $description $see-article } ;
 563
 564 HELP: unmarshall-ulonglong*
 565 { $values
 566     { "alien" alien }
 567     { "n" number }
 568 }
 569 { $description $see-article } ;
 570
 571 HELP: unmarshall-ulonglong*-free
 572 { $values
 573     { "alien" alien }
 574     { "n" number }
 575 }
 576 { $description $see-article } ;
 577
 578 HELP: unmarshall-ushort*
 579 { $values
 580     { "alien" alien }
 581     { "n" number }
 582 }
 583 { $description $see-article } ;
 584
 585 HELP: unmarshall-ushort*-free
 586 { $values
 587     { "alien" alien }
 588     { "n" number }
 589 }
 590 { $description $see-article } ;
 591
 592 HELP: unmarshaller
 593 { $values
 594     { "type" "a C type string" }
 595     { "quot" quotation }
 596 }
 597 { $description "Given a C type, returns a quotation that will unmarshall values of that type." } ;
 598
 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."
 602
 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 }
 610 $nl
 611 "Other marshalling and unmarshalling words in this vocabulary are not intended to be "
 612 "invoked directly."
 613 $nl
 614 "Most marshalling words allow non false c-ptrs to pass through unchanged."
 615
 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."
 623
 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."
 634 $nl
 635 "Primitive values require no unmarshalling. The factor FFI already does this."
 636 ;
 637
 638 ABOUT: "alien.marshall"