basis/io/servers/servers-docs.factor

   1 USING: calendar classes concurrency.semaphores help.markup
   2 help.syntax io io.sockets io.sockets.secure math quotations ;
   3 IN: io.servers
   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 } "."
   7 { $subsections
   8     "server-config-logging"
   9     "server-config-listen"
  10     "server-config-limit"
  11     "server-config-stream"
  12     "server-config-handler"
  13 } ;
  14
  15 ARTICLE: "server-config-logging" "Logging connections"
  16 "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." ;
  17
  18 ARTICLE: "server-config-listen" "Setting ports to listen on"
  19 "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" } "."
  20 $nl
  21 "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."
  22 $nl
  23 "Two utility words for producing address specifiers:"
  24 { $subsections
  25     local-server
  26     internet-server
  27 } ;
  28
  29 ARTICLE: "server-config-limit" "Limiting connections"
  30 "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."
  31 $nl
  32 "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."
  33 $nl
  34 "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." ;
  35
  36 ARTICLE: "server-config-stream" "Client stream parameters"
  37 "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." ;
  38
  39 ARTICLE: "server-config-handler" "Client handler quotation"
  40 "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:"
  41 { $list
  42     { $link input-stream }
  43     { $link output-stream }
  44     { $link local-address }
  45     { $link remote-address }
  46     { $link threaded-server }
  47 }
  48 "An alternate way to implement client handlers is to subclass " { $link threaded-server } ", and define a method on " { $link handle-client* } "."
  49 $nl
  50 "The two methods are equivalent, representing a functional versus an object-oriented approach to the problem." ;
  51
  52 ARTICLE: "server-examples" "Threaded server examples"
  53 "The " { $vocab-link "time-server" } " vocabulary implements a simple threaded server which sends the current time to the client. The " { $vocab-link "concurrency.distributed" } ", " { $vocab-link "ftp.server" } ", and " { $vocab-link "http.server" } " vocabularies demonstrate more complex usage of the threaded server library." ;
  54
  55 ARTICLE: "io.servers" "Threaded servers"
  56 "The " { $vocab-link "io.servers" } " 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."
  57 { $subsections "server-examples" }
  58 "Creating threaded servers with client handler quotations:"
  59 { $subsections <threaded-server> }
  60 "Client handlers can also be implemented by subclassing a threaded server; see " { $link "server-config-handler" } " for details:"
  61 { $subsections
  62     threaded-server
  63     new-threaded-server
  64     handle-client*
  65 }
  66 "The server must be configured before it can be started."
  67 { $subsections "server-config" }
  68 "Starting the server:"
  69 { $subsections start-server }
  70 "Stopping the server:"
  71 { $subsections stop-server }
  72 "Waiting for the server to stop:"
  73 { $subsections wait-for-server }
  74 "Combinator for running a server:"
  75 { $subsections with-threaded-server }
  76 "From within the dynamic scope of a client handler, several words can be used to interact with the threaded server:"
  77 { $subsections
  78     stop-this-server
  79     secure-port
  80     insecure-port
  81 }
  82 "Additionally, the " { $link local-address } " and "
  83 { $subsections remote-address } " variables are set, as in " { $link with-client } "." ;
  84
  85 ABOUT: "io.servers"
  86
  87 HELP: threaded-server
  88 { $var-description "In client handlers, stores the current threaded server instance." }
  89 { $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." } ;
  90
  91 HELP: new-threaded-server
  92 { $values { "encoding" "an encoding descriptor" } { "class" class } { "threaded-server" threaded-server } }
  93 { $description "Creates a new instance of a subclass of " { $link threaded-server } ". Subclasses can implement the " { $link handle-client* } " generic word." } ;
  94
  95 HELP: <threaded-server>
  96 { $values { "encoding" "an encoding descriptor" } { "threaded-server" threaded-server } }
  97 { $description "Creates a new threaded server with streams encoded " { $snippet "encoding" } ". Its slots should be filled in as per " { $link "server-config" } ", before " { $link start-server } " is called to begin waiting for connections." } ;
  98
  99 HELP: remote-address
 100 { $var-description "Variable holding the address specifier of the current client connection. See " { $link "network-addressing" } "." } ;
 101
 102 HELP: handle-client*
 103 { $values { "threaded-server" threaded-server } }
 104 { $contract "Handles a client connection. Default implementation calls quotation stored in the " { $snippet "handler" } " slot of the threaded server." } ;
 105
 106 HELP: start-server
 107 { $values { "threaded-server" threaded-server } }
 108 { $description "Starts a threaded server and returns after the server is fully running. Throws an error if any of the ports cannot be aquired." }
 109 { $notes "Use " { $link stop-server } " or " { $link stop-this-server } " to stop the server." } ;
 110
 111 HELP: stop-server
 112 { $values { "threaded-server" threaded-server } }
 113 { $description "Stops a threaded server, preventing it from accepting any more connections. All client connections which have already been opened continue to be serviced." } ;
 114
 115 HELP: wait-for-server
 116 { $values { "threaded-server" threaded-server } }
 117 { $description "Waits for a threaded server to stop serving new connections." } ;
 118
 119 HELP: stop-this-server
 120 { $description "Stops the current threaded server, preventing it from accepting any more connections. All client connections which have already been opened continue to be serviced." } ;
 121
 122 HELP: with-threaded-server
 123 { $values
 124     { "threaded-server" threaded-server } { "quot" quotation }
 125 }
 126 { $description "Runs a server and calls a quotation, stopping the server once the quotation returns." } ;
 127
 128 HELP: secure-port
 129 { $values { "n/f" { $maybe integer } } }
 130 { $description "Outputs one of the port numbers on which the current threaded server accepts secure socket connections. Outputs " { $link f } " if the current threaded server does not accept secure socket connections." }
 131 { $notes "Can only be used from the dynamic scope of a " { $link handle-client* } " call." } ;
 132
 133 HELP: insecure-port
 134 { $values { "n/f" { $maybe integer } } }
 135 { $description "Outputs one of the port numbers on which the current threaded server accepts ordinary socket connections. Outputs " { $link f } " if the current threaded server does not accept ordinary socket connections." }
 136 { $notes "Can only be used from the dynamic scope of a " { $link handle-client* } " call." } ;