extra/memory/pools/pools-docs.factor

   1 ! (c)2009 Joe Groff bsd license
   2 USING: classes help.markup help.syntax kernel math ;
   3 IN: memory.pools
   4
   5 HELP: <pool>
   6 { $values
   7     { "size" integer } { "class" class }
   8     { "pool" pool }
   9 }
  10 { $description "Creates a " { $link pool } " of " { $snippet "size" } " objects of " { $snippet "class" } "." } ;
  11
  12 HELP: POOL:
  13 { $syntax "POOL: class size" }
  14 { $description "Creates a " { $link pool } " of " { $snippet "size" } " objects of " { $snippet "class" } ", and associates it with the class using " { $link set-class-pool } "." } ;
  15
  16 HELP: class-pool
  17 { $values
  18     { "class" class }
  19     { "pool" pool }
  20 }
  21 { $description "Returns the " { $link pool } " associated with " { $snippet "class" } ", or " { $link f } " if no pool is associated." } ;
  22
  23 HELP: free-to-pool
  24 { $values
  25     { "object" object }
  26 }
  27 { $description "Frees an object from the " { $link pool } " it was allocated from. The object must have been allocated by " { $link new-from-pool } "." } ;
  28
  29 HELP: new-from-pool
  30 { $values
  31     { "class" class }
  32     { "object" object }
  33 }
  34 { $description "Allocates an object from the " { $link pool } " associated with " { $snippet "class" } ". If the pool is exhausted, " { $link f } " is returned." } ;
  35
  36 { POSTPONE: POOL: class-pool set-class-pool new-from-pool free-to-pool } related-words
  37
  38 HELP: pool
  39 { $class-description "A " { $snippet "pool" } " contains a fixed-size set of preallocated tuple objects. Once the pool has been allocated, its objects can be allocated with " { $link pool-new } " and freed with " { $link pool-free } " in constant time. A pool can also be associated with its class with the " { $link POSTPONE: POOL: } " syntax or the " { $link set-class-pool } " word, after which the words " { $link new-from-pool } " and " { $link free-to-pool } " can be used with the class name to allocate and free objects." } ;
  40
  41 HELP: pool-free
  42 { $values
  43     { "object" object } { "pool" pool }
  44 }
  45 { $description "Frees an object back into " { $link pool } "." } ;
  46
  47 HELP: pool-size
  48 { $values
  49     { "pool" pool }
  50     { "size" integer }
  51 }
  52 { $description "Returns the number of unallocated objects inside a " { $link pool } "." } ;
  53
  54 HELP: pool-new
  55 { $values
  56     { "pool" pool }
  57     { "object" object }
  58 }
  59 { $description "Returns an unallocated object out of a " { $link pool } ". If the pool is exhausted, " { $link f } " is returned." } ;
  60
  61 { pool <pool> pool-new pool-free pool-size } related-words
  62
  63 HELP: set-class-pool
  64 { $values
  65     { "class" class } { "pool" pool }
  66 }
  67 { $description "Associates a " { $link pool } " with " { $snippet "class" } "." } ;
  68
  69 ARTICLE: "memory.pools" "Pools"
  70 "The " { $vocab-link "memory.pools" } " vocabulary provides " { $link pool } " objects which manage preallocated collections of objects."
  71 { $subsections
  72     pool
  73     POSTPONE: POOL:
  74     new-from-pool
  75     free-to-pool
  76 } ;
  77
  78 ABOUT: "memory.pools"