basis/io/pools/pools-docs.factor

   1 IN: io.pools
   2 USING: help.markup help.syntax destructors quotations ;
   3
   4 HELP: pool
   5 { $class-description "A connection pool. Instances of this class are not intended to be instantiated directly, only subclasses should be instantiated, for example " { $link datagram-pool } "." } ;
   6
   7 HELP: <pool>
   8 { $values { "class" "a subclass of " { $link pool } } { "pool" pool } }
   9 { $description "Creates a new connection pool." }
  10 { $notes "To avoid resource leaks, pools must be disposed of by calling " { $link dispose } " when no longer in use." } ;
  11
  12 HELP: with-pool
  13 { $values { "pool" pool } { "quot" quotation } }
  14 { $description "Calls a quotation in a new dynamic scope with the " { $link pool } " variable set to " { $snippet "pool" } ". The pool is disposed of after the quotation returns, or if an error is thrown." } ;
  15
  16 HELP: acquire-connection
  17 { $values { "pool" pool } { "conn" "a connection" } }
  18 { $description "Outputs a connection from the pool, preferring to take an existing one, creating a new one with " { $link make-connection } " if the pool is empty." } ;
  19
  20 HELP: return-connection
  21 { $values { "conn" "a connection" } { "pool" pool } }
  22 { $description "Returns a connection to the pool." } ;
  23
  24 HELP: with-pooled-connection
  25 { $values { "pool" pool } { "quot" { $quotation "( conn -- )" } } }
  26 { $description "Calls a quotation with a pooled connection on the stack. If the quotation returns successfully, the connection is returned to the pool; if the quotation throws an error, the connection is disposed of with " { $link dispose } "." } ;
  27
  28 HELP: make-connection
  29 { $values { "pool" pool } { "conn" "a connection" } }
  30 { $contract "Makes a connection for the pool." } ;
  31
  32 HELP: datagram-pool
  33 { $class-description "A pool of datagram sockets bound to the address stored in the " { $snippet "addrspec" } " slot." } ;
  34
  35 HELP: <datagram-pool>
  36 { $values { "addrspec" "an address specifier" } { "pool" datagram-pool } }
  37 { $description "Creates a new " { $link datagram-pool } ". The port number of the " { $snippet "addrspec" } " should be 0, otherwise creation of more than one datagram socket will raise an error." }
  38 { $examples
  39     { $code "f 0 <inet4> <datagram-pool>" }
  40 } ;
  41
  42 ARTICLE: "io.pools" "Connection pools"
  43 "Connection pools are implemented in the " { $snippet "io.pools" } " vocabulary. They are used to reuse sockets and connections which may be potentially expensive to create and destroy."
  44 $nl
  45 "The class of connection pools:"
  46 { $subsections pool }
  47 "Creating connection pools:"
  48 { $subsections <pool> }
  49 "A utility combinator:"
  50 { $subsections with-pool }
  51 "Acquiring and returning connections, and a utility combinator:"
  52 { $subsections
  53     acquire-connection
  54     return-connection
  55     with-pooled-connection
  56 }
  57 "Pools are not created directly, instead one uses subclasses which implement a generic word:"
  58 { $subsections make-connection }
  59 "One example is a datagram socket pool:"
  60 { $subsections
  61     datagram-pool
  62     <datagram-pool>
  63 } ;
  64
  65 ABOUT: "io.pools"