basis/io/servers/connection/connection-docs.factor

   1 IN: io.servers.connection
   2 USING: help help.syntax help.markup io io.sockets
   3 io.sockets.secure concurrency.semaphores calendar classes math ;
   4
   5 ARTICLE: "server-config" "Threaded server configuration"
   6 "The " { $link threaded-server } " tuple has a variety of slots which can be set before starting the server with " { $link start-server } " or " { $link start-server* } "."
   7 { $subsection "server-config-logging" }
   8 { $subsection "server-config-listen" }
   9 { $subsection "server-config-limit" }
  10 { $subsection "server-config-stream" }
  11 { $subsection "server-config-handler" } ;
  12
  13 ARTICLE: "server-config-logging" "Logging connections"
  14 "The " { $snippet "name" } " slot of a threaded server instance should be set to a string naming the logging service name to use. See " { $link "logging" } " for details." ;
  15
  16 ARTICLE: "server-config-listen" "Setting ports to listen on"
  17 "The " { $snippet "insecure" } " slot of a threaded server instance contains an integer, an address specifier, or a sequence of address specifiers. Integer port numbers are interpreted as an " { $link inet4 } "/" { $link inet6 } " pair listening on all interfaces for given port number. All other address specifiers are interpeted as per " { $link "network-addressing" } "."
  18 $nl
  19 "The " { $snippet "secure" } " slot of a threaded server instance is interpreted in the same manner as the " { $snippet "insecure" } " slot, except that secure encrypted connections are then allowed. If this slot is set, the " { $snippet "secure-config" } " slot should also be set to a " { $link secure-config } " instance containing SSL server configuration. See " { $link "ssl-config" } " for details."
  20 $nl
  21 "Two utility words for producing address specifiers:"
  22 { $subsection local-server }
  23 { $subsection internet-server } ;
  24
  25 ARTICLE: "server-config-limit" "Limiting connections"
  26 "The " { $snippet "max-connections" } " slot is initially set to " { $link f } ", which disables connection limiting, but can be set to an integer specifying the maximum number of simultaneous connections."
  27 $nl
  28 "Another method to limit connections is to set the " { $snippet "semaphore" } " slot to a " { $link semaphore } ". The server will hold the semaphore while servicing the client connection."
  29 $nl
  30 "Setting the " { $snippet "max-connections" } " slot is equivalent to storing a semaphore with this initial count in the " { $snippet "semaphore" } " slot. The " { $snippet "semaphore" } " slot is useful for enforcing a maximum connection count shared between multiple threaded servers. See " { $link "concurrency.semaphores" } " for details." ;
  31
  32 ARTICLE: "server-config-stream" "Client stream parameters"
  33 "The " { $snippet "encoding" } " and " { $snippet "timeout" } " slots of the threaded server can be set to an encoding descriptor or a " { $link duration } ", respectively. See " { $link "io.encodings" } " and " { $link "io.timeouts" } " for details." ;
  34
  35 ARTICLE: "server-config-handler" "Client handler quotation"
  36 "The " { $snippet "handler" } " slot of a threaded server instance should be set to a quotation which handles client connections. Client handlers are run in their own thread, with the following variables rebound:"
  37 { $list
  38     { $link input-stream }
  39     { $link output-stream }
  40     { $link local-address }
  41     { $link remote-address }
  42     { $link threaded-server }
  43 }
  44 "An alternate way to implement client handlers is to subclass " { $link threaded-server } ", and define a method on " { $link handle-client* } "."
  45 $nl
  46 "The two methods are equivalent, representing a functional versus an object-oriented approach to the problem." ;
  47
  48 ARTICLE: "io.servers.connection" "Threaded servers"
  49 "The " { $vocab-link "io.servers.connection" } " vocabulary implements a generic server abstraction for " { $link "network-connection" } ". A set of threads listen for connections, and additional threads are spawned for each client connection. In addition to this basic functionality, it provides some advanced features such as logging, connection limits and secure socket support."
  50 { $subsection threaded-server }
  51 { $subsection "server-config" }
  52 "Creating threaded servers with client handler quotations:"
  53 { $subsection <threaded-server> }
  54 "Client handlers can also be implemented by subclassing a threaded server; see " { $link "server-config-handler" } " for details:"
  55 { $subsection new-threaded-server }
  56 { $subsection handle-client* }
  57 "Starting the server:"
  58 { $subsection start-server }
  59 { $subsection start-server* }
  60 { $subsection wait-for-server }
  61 "Stopping the server:"
  62 { $subsection stop-server }
  63 "From within the dynamic scope of a client handler, several words can be used to interact with the threaded server:"
  64 { $subsection remote-address }
  65 { $subsection stop-this-server }
  66 { $subsection secure-port }
  67 { $subsection insecure-port }
  68 "Additionally, the " { $link local-address } " variable is set, as in " { $link with-client } "." ;
  69
  70 ABOUT: "io.servers.connection"
  71
  72 HELP: threaded-server
  73 { $var-description "In client handlers, stores the current threaded server instance." }
  74 { $class-description "The class of threaded servers. New instances are created with " { $link <threaded-server> } ". This class may be subclassed, and instances of subclasses should be created with " { $link new-threaded-server } ". See " { $link "server-config" } " for slot documentation." } ;
  75
  76 HELP: new-threaded-server
  77 { $values { "class" class } { "threaded-server" threaded-server } }
  78 { $description "Creates a new instance of a subclass of " { $link threaded-server } ". Subclasses can implement the " { $link handle-client* } " generic word." } ;
  79
  80 HELP: <threaded-server>
  81 { $values { "threaded-server" threaded-server } }
  82 { $description "Creates a new threaded server. Its slots should be filled in as per " { $link "server-config" } ", before " { $link start-server } " is called to begin waiting for connections." } ;
  83
  84 HELP: remote-address
  85 { $var-description "Variable holding the address specifier of the current client connection. See " { $link "network-addressing" } "." } ;
  86
  87 HELP: handle-client*
  88 { $values { "threaded-server" threaded-server } }
  89 { $contract "Handles a client connection. Default implementation calls quotation stored in the " { $snippet "handler" } " slot of the threaded server." } ;
  90
  91 HELP: start-server
  92 { $values { "threaded-server" threaded-server } }
  93 { $description "Starts a threaded server." }
  94 { $notes "Use " { $link stop-server } " or " { $link stop-this-server } " to stop the server." } ;
  95
  96 HELP: wait-for-server
  97 { $values { "threaded-server" threaded-server } }
  98 { $description "Waits for a threaded server to begin accepting connections." } ;
  99
 100 HELP: start-server*
 101 { $values { "threaded-server" threaded-server } }
 102 { $description "Starts a threaded server, returning as soon as it is ready to begin accepting connections." } ;
 103
 104 HELP: stop-server
 105 { $values { "threaded-server" threaded-server } }
 106 { $description "Stops a threaded server, preventing it from accepting any more connections and returning to the caller of " { $link start-server } ". All client connections which have already been opened continue to be serviced." } ;
 107
 108 HELP: stop-this-server
 109 { $description "Stops the current threaded server, preventing it from accepting any more connections and returning to the caller of " { $link start-server } ". All client connections which have already been opened continue to be serviced." } ;
 110
 111 HELP: secure-port
 112 { $values { "n" "an " { $link integer } " or " { $link f } } }
 113 { $description "Outputs the port number on which the current threaded server accepts secure socket connections. Outputs " { $link f } " if the current threaded server does not accept secure socket connections." }
 114 { $notes "Can only be used from the dynamic scope of a " { $link handle-client* } " call." } ;
 115
 116 HELP: insecure-port
 117 { $values { "n" "an " { $link integer } " or " { $link f } } }
 118 { $description "Outputs the port number on which the current threaded server accepts ordinary socket connections. Outputs " { $link f } " if the current threaded server does not accept ordinary socket connections." }
 119 { $notes "Can only be used from the dynamic scope of a " { $link handle-client* } " call." } ;