extra/memory/piles/piles-docs.factor

   1 ! (c)2009 Joe Groff bsd license
   2 USING: alien destructors help.markup help.syntax kernel math ;
   3 IN: memory.piles
   4
   5 HELP: <pile>
   6 { $values
   7     { "size" integer }
   8     { "pile" pile }
   9 }
  10 { $description "Allocates " { $snippet "size" } " bytes of raw memory for a new " { $link pile } ". The pile should be " { $link dispose } "d when it is no longer needed." } ;
  11
  12 HELP: not-enough-pile-space
  13 { $values
  14     { "pile" pile }
  15 }
  16 { $description "This error is thrown by " { $link pile-alloc } " when the " { $link pile } " does not have enough remaining space for the requested allocation." } ;
  17
  18 HELP: pile
  19 { $class-description "A " { $snippet "pile" } " is a block of raw memory that can be apportioned out in constant time. A pile is allocated using the " { $link <pile> } " word. Blocks of memory can be requested from the pile using " { $link pile-alloc } ", and all the pile's memory can be reclaimed with " { $link pile-empty } "." } ;
  20
  21 HELP: pile-align
  22 { $values
  23     { "pile" pile } { "align" "a power of two" }
  24 }
  25 { $description "Adjusts a " { $link pile } "'s internal state so that the next call to " { $link pile-alloc } " will return a pointer aligned to " { $snippet "align" } " bytes relative to the pile's initial offset." } ;
  26
  27 HELP: pile-alloc
  28 { $values
  29     { "pile" pile } { "size" integer }
  30     { "alien" alien }
  31 }
  32 { $description "Requests " { $snippet "size" } " bytes from a " { $link pile } ". If the pile does not have enough space to satisfy the request, a " { $link not-enough-pile-space } " error is thrown." } ;
  33
  34 HELP: <pile-c-array>
  35 { $values
  36     { "pile" pile } { "n" integer } { "c-type" "a C type" }
  37     { "alien" alien }
  38 }
  39 { $description "Requests enough space from a " { $link pile } " to hold " { $snippet "n" } " values of " { $snippet "c-type" } ". If the pile does not have enough space to satisfy the request, a " { $link not-enough-pile-space } " error is thrown." } ;
  40
  41 HELP: <pile-c-object>
  42 { $values
  43     { "pile" pile } { "c-type" "a C type" }
  44     { "alien" alien }
  45 }
  46 { $description "Requests enough space from a " { $link pile } " to hold a value of " { $snippet "c-type" } ". If the pile does not have enough space to satisfy the request, a " { $link not-enough-pile-space } " error is thrown." } ;
  47
  48 HELP: pile-empty
  49 { $values
  50     { "pile" pile }
  51 }
  52 { $description "Reclaims all the memory allocated out of a " { $link pile } ". Allocations will resume from the beginning of the pile." } ;
  53
  54 ARTICLE: "memory.piles" "Piles"
  55 "A " { $link pile } " is a block of raw memory. Portions of its memory can be allocated from the beginning of the pile in constant time, and the pile can be emptied and its pointer reset to the beginning."
  56 { $subsections
  57     <pile>
  58     pile-alloc
  59     <pile-c-array>
  60     <pile-c-object>
  61     pile-align
  62     pile-empty
  63 }
  64 "An example of the utility of piles is in video games. For example, the game Abuse was scripted with a Lisp dialect. In order to avoid stalls from traditional GC or heap-based allocators, the Abuse Lisp VM would allocate values from a preallocated pile over the course of a frame, and release the entire pile at the end of the frame." ;
  65
  66 ABOUT: "memory.piles"