extra/memory/pools/pools-docs.factor

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