extra/memory/piles/piles-docs.factor

   1 ! Copyright (C) 2009 Joe Groff.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: alien destructors help.markup help.syntax kernel math ;
   4 IN: memory.piles
   5
   6 HELP: <pile>
   7 { $values
   8     { "size" integer }
   9     { "pile" pile }
  10 }
  11 { $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." } ;
  12
  13 HELP: not-enough-pile-space
  14 { $values
  15     { "pile" pile }
  16 }
  17 { $description "This error is thrown by " { $link pile-alloc } " when the " { $link pile } " does not have enough remaining space for the requested allocation." } ;
  18
  19 HELP: pile
  20 { $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 } "." } ;
  21
  22 HELP: pile-align
  23 { $values
  24     { "pile" pile } { "align" "a power of two" }
  25 }
  26 { $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." } ;
  27
  28 HELP: pile-alloc
  29 { $values
  30     { "pile" pile } { "size" integer }
  31     { "alien" alien }
  32 }
  33 { $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." } ;
  34
  35 HELP: <pile-c-array>
  36 { $values
  37     { "pile" pile } { "n" integer } { "c-type" "a C type" }
  38     { "alien" alien }
  39 }
  40 { $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." } ;
  41
  42 HELP: <pile-c-object>
  43 { $values
  44     { "pile" pile } { "c-type" "a C type" }
  45     { "alien" alien }
  46 }
  47 { $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." } ;
  48
  49 HELP: pile-empty
  50 { $values
  51     { "pile" pile }
  52 }
  53 { $description "Reclaims all the memory allocated out of a " { $link pile } ". Allocations will resume from the beginning of the pile." } ;
  54
  55 ARTICLE: "memory.piles" "Piles"
  56 "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."
  57 { $subsections
  58     <pile>
  59     pile-alloc
  60     <pile-c-array>
  61     <pile-c-object>
  62     pile-align
  63     pile-empty
  64 }
  65 "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." ;
  66
  67 ABOUT: "memory.piles"