diff --git a/basis/alien/c-types/c-types-docs.factor b/basis/alien/c-types/c-types-docs.factor index dc29ea9bb3..46afc05e2d 100644 --- a/basis/alien/c-types/c-types-docs.factor +++ b/basis/alien/c-types/c-types-docs.factor @@ -217,6 +217,8 @@ $nl "Utilities for automatically freeing memory in conjunction with " { $link with-destructors } ":" { $subsection &free } { $subsection |free } +"The " { $link &free } " and " { $link |free } " words are generated using " { $link "alien.destructors" } "." +$nl "You can unsafely copy a range of bytes from one memory location to another:" { $subsection memcpy } "You can copy a range of bytes from memory into a byte array:" @@ -243,4 +245,6 @@ $nl "New C types can be defined:" { $subsection "c-structs" } { $subsection "c-unions" } +"A utility for defining " { $link "destructors" } " for deallocating memory:" +{ $subsection "alien.destructors" } { $see-also "aliens" } ; diff --git a/basis/alien/destructors/destructors-docs.factor b/basis/alien/destructors/destructors-docs.factor new file mode 100644 index 0000000000..bc08dc7486 --- /dev/null +++ b/basis/alien/destructors/destructors-docs.factor @@ -0,0 +1,30 @@ +IN: alien.destructors +USING: help.markup help.syntax alien destructors ; + +HELP: DESTRUCTOR: +{ $syntax "DESTRUCTOR: word" } +{ $description "Defines four things:" + { $list + { "a tuple named " { $snippet "word" } " with a single slot holding a " { $link c-ptr } } + { "a " { $link dispose } " method on the tuple which calls " { $snippet "word" } " with the " { $link c-ptr } } + { "a pair of words, " { $snippet "&word" } " and " { $snippet "|word" } ", which call " { $link &dispose } " and " { $link |dispose } " with a new instance of the tuple" } + } + "The " { $snippet "word" } " must be defined in the current vocabulary, and must have stack effect " { $snippet "( c-ptr -- )" } "." +} +{ $examples + "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," + { $code + "FUNCTION: void g_object_unref ( gpointer object ) ;" + "DESTRUCTOR: g_object_unref" + } + "Now, memory management becomes easier:" + { $code + "[ g_new_foo &g_object_unref ... ] with-destructors" + } +} ; + +ARTICLE: "alien.destructors" "Alien destructors" +"The " { $vocab-link "alien.destructors" } " vocabulary defines a utility parsing word for defining new disposable classes." +{ $subsection POSTPONE: DESTRUCTOR: } ; + +ABOUT: "alien.destructors" \ No newline at end of file