Abstract out connection pooling into io.pools, add summary and tags to a few places

extra/db/pooling/pooling-tests.factor

@@ -1,8 +0,0 @@
-IN: db.pooling.tests
-USING: db.pooling tools.test ;
-
-\ <pool> must-infer
-
-{ 2 0 } [ [ ] with-db-pool ] must-infer-as
-
-{ 1 0 } [ [ ] with-pooled-connection ] must-infer-as

extra/db/pooling/pooling.factor

@@ -1,43 +0,0 @@
-! Copyright (C) 2008 Slava Pestov.
-! See http://factorcode.org/license.txt for BSD license.
-USING: accessors kernel arrays namespaces sequences continuations
-destructors db ;
-IN: db.pooling
-
-TUPLE: pool db params connections ;
-
-: <pool> ( db params -- pool )
-    V{ } clone pool boa ;
-
-M: pool dispose [ dispose-each f ] change-connections drop ;
-
-: with-db-pool ( db params quot -- )
-    >r <pool> r> [ pool swap with-variable ] curry with-disposal ; inline
-
-TUPLE: return-connection db pool ;
-
-: return-connection ( db pool -- )
-    connections>> push ;
-
-: new-connection ( pool -- )
-    [ [ db>> ] [ params>> ] bi make-db db-open ] keep
-    return-connection ;
-
-: acquire-connection ( pool -- db )
-    [ dup connections>> empty? ] [ dup new-connection ] [ ] while
-    connections>> pop ;
-
-: (with-pooled-connection) ( db pool quot -- )
-    [ >r drop db r> with-variable ]
-    [ drop return-connection ]
-    3bi ; inline
-
-: with-pooled-connection ( pool quot -- )
-    >r [ acquire-connection ] keep r>
-    [ (with-pooled-connection) ] [ ] [ 2drop dispose ] cleanup ; inline
-
-M: return-connection dispose
-    [ db>> ] [ pool>> ] bi return-connection ;
-
-: return-connection-later ( db pool -- )
-    \ return-connection boa &dispose drop ;

extra/db/pools/pools-tests.factor

@@ -0,0 +1,8 @@
+IN: db.pools.tests
+USING: db.pools tools.test ;
+
+\ <db-pool> must-infer
+
+{ 2 0 } [ [ ] with-db-pool ] must-infer-as
+
+{ 1 0 } [ [ ] with-pooled-db ] must-infer-as

extra/db/pools/pools.factor

@@ -0,0 +1,21 @@
+! Copyright (C) 2008 Slava Pestov.
+! See http://factorcode.org/license.txt for BSD license.
+USING: accessors kernel arrays namespaces sequences continuations
+io.pools db ;
+IN: db.pools
+
+TUPLE: db-pool < pool db params ;
+
+: <db-pool> ( db params -- pool )
+    db-pool <pool>
+        swap >>params
+        swap >>db ;
+
+: with-db-pool ( db params quot -- )
+    >r <db-pool> r> with-pool ; inline
+
+M: db-pool make-connection ( pool -- )
+    [ db>> ] [ params>> ] bi make-db db-open ;
+
+: with-pooled-db ( pool quot -- )
+    [ db swap with-variable ] curry with-pooled-connection ; inline

extra/ftp/client/tags.txt

@@ -0,0 +1 @@
+network

extra/ftp/server/tags.txt

@@ -0,0 +1 @@
+network

extra/ftp/tags.txt

@@ -0,0 +1 @@
+network

extra/http/server/db/db.factor

@@ -1,13 +1,13 @@
 ! Copyright (C) 2008 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
-USING: db db.pooling http.server http.server.sessions kernel
-accessors continuations namespaces destructors ;
+USING: db db.pools io.pools http.server http.server.sessions
+kernel accessors continuations namespaces destructors ;
 IN: http.server.db
 
 TUPLE: db-persistence < filter-responder pool ;
 
 : <db-persistence> ( responder db params -- responder' )
-    <pool> db-persistence boa ;
+    <db-pool> db-persistence boa ;
 
 M: db-persistence call-responder*
     [

extra/io/pools/authors.txt

@@ -0,0 +1 @@
+Slava Pestov

extra/io/pools/pools-docs.factor

@@ -0,0 +1,61 @@
+IN: io.pools
+USING: help.markup help.syntax destructors quotations ;
+
+HELP: pool
+{ $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 } "." } ;
+
+HELP: <pool>
+{ $values { "class" "a subclass of " { $link pool } } { "pool" pool } }
+{ $description "Creates a new connection pool." }
+{ $notes "To avoid resource leaks, pools must be disposed of by calling " { $link dispose } " when no longer in use." } ;
+
+HELP: with-pool
+{ $values { "pool" pool } { "quot" quotation } }
+{ $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." } ;
+
+HELP: acquire-connection
+{ $values { "pool" pool } { "conn" "a connection" } }
+{ $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." } ;
+
+HELP: return-connection
+{ $values { "conn" "a connection" } { "pool" pool } }
+{ $description "Returns a connection to the pool." } ;
+
+HELP: with-pooled-connection
+{ $values { "pool" pool } { "quot" "a quotation with stack effect " { $snippet "( conn -- )" } } }
+{ $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 } "." } ;
+
+HELP: make-connection
+{ $values { "pool" pool } { "conn" "a connection" } }
+{ $contract "Makes a connection for the pool." } ;
+
+HELP: datagram-pool
+{ $class-description "A pool of datagram sockets bound to the address stored in the " { $snippet "addrspec" } " slot." } ;
+
+HELP: <datagram-pool>
+{ $values { "addrspec" "an address specifier" } { "pool" datagram-pool } }
+{ $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." }
+{ $examples
+    { $code "f 0 <inet4> <datagram-pool>" }
+} ;
+
+ARTICLE: "io.pools" "Connection pools"
+"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."
+$nl
+"The class of connection pools:"
+{ $subsection pool }
+"Creating connection pools:"
+{ $subsection <pool> }
+"A utility combinator:"
+{ $subsection with-pool }
+"Acquiring and returning connections, and a utility combinator:"
+{ $subsection acquire-connection }
+{ $subsection return-connection }
+{ $subsection with-pooled-connection }
+"Pools are not created directly, instead one uses subclasses which implement a generic word:"
+{ $subsection make-connection }
+"One example is a datagram socket pool:"
+{ $subsection datagram-pool }
+{ $subsection <datagram-pool> } ;
+
+ABOUT: "io.pools"

extra/io/pools/pools.factor

@@ -0,0 +1,50 @@
+! Copyright (C) 2008 Slava Pestov.
+! See http://factorcode.org/license.txt for BSD license.
+USING: accessors kernel arrays namespaces sequences continuations
+destructors io.sockets ;
+IN: io.pools
+
+TUPLE: pool connections disposed ;
+
+: <pool> ( class -- pool )
+    new V{ } clone >>connections ; inline
+
+M: pool dispose* connections>> dispose-each ;
+
+: with-pool ( pool quot -- )
+    [ pool swap with-variable ] curry with-disposal ; inline
+
+TUPLE: return-connection conn pool ;
+
+: return-connection ( conn pool -- )
+    dup check-disposed connections>> push ;
+
+GENERIC: make-connection ( pool -- conn )
+
+: new-connection ( pool -- )
+    [ make-connection ] keep return-connection ;
+
+: acquire-connection ( pool -- conn )
+    dup check-disposed
+    [ dup connections>> empty? ] [ dup new-connection ] [ ] while
+    connections>> pop ;
+
+: (with-pooled-connection) ( conn pool quot -- )
+    [ nip call ] [ drop return-connection ] 3bi ; inline
+
+: with-pooled-connection ( pool quot -- )
+    >r [ acquire-connection ] keep r>
+    [ (with-pooled-connection) ] [ ] [ 2drop dispose ] cleanup ; inline
+
+M: return-connection dispose
+    [ conn>> ] [ pool>> ] bi return-connection ;
+
+: return-connection-later ( db pool -- )
+    \ return-connection boa &dispose drop ;
+
+TUPLE: datagram-pool < pool addrspec ;
+
+: <datagram-pool> ( addrspec -- pool )
+    datagram-pool <pool> swap >>addrspec ;
+
+M: datagram-pool make-connection addrspec>> <datagram> ;

extra/io/pools/summary.txt

@@ -0,0 +1 @@
+Abstract connection pooling

extra/io/pools/tags.txt

@@ -0,0 +1 @@
+network

extra/io/server/tags.txt

@@ -0,0 +1 @@
+network

extra/io/sockets/secure/authors.txt

@@ -0,0 +1 @@
+Slava Pestov

extra/io/sockets/secure/summary.txt

@@ -0,0 +1 @@
+Secure sockets (SSL, TLS)

extra/io/sockets/secure/tags.txt

@@ -0,0 +1 @@
+network