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 { $subsection pool }
  47 "Creating connection pools:"
  48 { $subsection <pool> }
  49 "A utility combinator:"
  50 { $subsection with-pool }
  51 "Acquiring and returning connections, and a utility combinator:"
  52 { $subsection acquire-connection }
  53 { $subsection return-connection }
  54 { $subsection with-pooled-connection }
  55 "Pools are not created directly, instead one uses subclasses which implement a generic word:"
  56 { $subsection make-connection }
  57 "One example is a datagram socket pool:"
  58 { $subsection datagram-pool }
  59 { $subsection <datagram-pool> } ;
  60
  61 ABOUT: "io.pools"