basis/alien/destructors/destructors-docs.factor

   1 IN: alien.destructors
   2 USING: help.markup help.syntax alien destructors ;
   3
   4 HELP: DESTRUCTOR:
   5 { $syntax "DESTRUCTOR: word" }
   6 { $description "Defines four things:"
   7   { $list
   8     { "a tuple named " { $snippet "word" } " with a single slot holding a " { $link c-ptr } }
   9     { "a " { $link dispose } " method on the tuple which calls " { $snippet "word" } " with the " { $link c-ptr } }
  10     { "a pair of words, " { $snippet "&word" } " and " { $snippet "|word" } ", which call " { $link &dispose } " and " { $link |dispose } " with a new instance of the tuple" }
  11   }
  12   "The " { $snippet "word" } " must be defined in the current vocabulary, and must have stack effect " { $snippet "( c-ptr -- )" } "."
  13 }
  14 { $examples
  15   "Suppose you are writing a binding to the GLib library, which as a " { $snippet "g_object_unref" } " function. Then you can define the function and destructor like so,"
  16   { $code
  17     "FUNCTION: void g_object_unref ( gpointer object ) ;"
  18     "DESTRUCTOR: g_object_unref"
  19   }
  20   "Now, memory management becomes easier:"
  21   { $code
  22     "[ g_new_foo &g_object_unref ... ] with-destructors"
  23   }
  24 } ;
  25
  26 ARTICLE: "alien.destructors" "Alien destructors"
  27 "The " { $vocab-link "alien.destructors" } " vocabulary defines a utility parsing word for defining new disposable classes."
  28 { $subsections POSTPONE: DESTRUCTOR: } ;
  29
  30 ABOUT: "alien.destructors"