factor/library/compiler/alien/malloc.facts

IN: libc
USING: help ;

HELP: malloc ( size -- alien )
{ $values { "size" "a non-negative integer" } { "alien" "an alien address" } }
{ $description "Allocates a block of " { $snippet "size" } " bytes from the operating system. The contents of the block are undefined."
$terpri
"Outputs " { $link f } " if memory allocation failed, so calls to this word should be followed by a call to " { $link check-ptr } "." }
{ $warning "Don't forget to deallocate the memory with a call to " { $link free } "." } ;

HELP: calloc ( count size -- alien )
{ $values { "count" "a non-negative integer" } { "size" "a non-negative integer" } { "alien" "an alien address" } }
{ $description "Allocates a block of " { $snippet "count * size" } " bytes from the operating system. The contents of the block are initially zero."
$terpri
"Outputs " { $link f } " if memory allocation failed, so calls to this word should be followed by a call to " { $link check-ptr } "." }
{ $warning "Don't forget to deallocate the memory with a call to " { $link free } "." } ;

HELP: realloc ( alien size -- newalien )
{ $values { "alien" "an alien address" } { "size" "a non-negative integer" } { "newalien" "an alien address" } }
{ $description "Allocates a new block of " { $snippet "size" } " bytes from the operating system. The contents of " { $snippet "alien" } ", which itself must be a block previously returned by " { $link malloc } " or " { $link realloc } ", are copied into the new block, and the old block is freed."
$terpri
"Outputs " { $link f } " if memory allocation failed, so calls to this word should be followed by a call to " { $link check-ptr } "." }
{ $warning "Don't forget to deallocate the memory with a call to " { $link free } "." } ;

HELP: memcpy ( dst src size -- )
{ $values { "dst" "an alien address" } { "src" "an alien address" } { "size" "a non-negative integer" } }
{ $description "Copies " { $snippet "size" } " bytes from " { $snippet "src" } " to " { $snippet "dst" } "." }
{ $warning "As per the BSD C library documentation, the behavior is undefined if the source and destination overlap." } ;

HELP: check-ptr
{ $values { "c-ptr" "an alien address, byte array, or " { $link f } } { "checked" "an alien address or byte array with non-zero address" } }
{ $description "Throws an error if the input is " { $link f } ". Otherwise the object remains on the data stack. This word should be used to check the return values of " { $link malloc } " and " { $link realloc } " before use." }
{ $error-description "Callers of " { $link malloc } " and " { $link realloc } " should use " { $link check-ptr } " to throw an error in the case of a memory allocation failure." } ;

HELP: free ( ptr -- )
{ $values { "ptr" "an alien address" } }
{ $description "Deallocates a block of memory allocated by " { $link malloc } ", " { $link calloc } " or " { $link realloc } "." } ;

HELP: with-malloc
{ $values { "n" "a positive integer" } { "quot" "a quotation with stack effect " { $snippet "( c-ptr -- )" } } }
{ $description "Allocates a zeroed block of " { $snippet "n" } " bytes and passes it to the quotation. When the quotation returns, the block is freed." } ;