USING: help io io-internals threads ;

HELP: io-multiplex "( ms -- )"
{ $values { "ms" "a non-negative integer" } }
{ $description "Waits up to " { $snippet "ms" } " milliseconds for pending I/O requests to complete." }
{ $warning "If an I/O request completes during the time period, its continuation is resumed and the current one is not saved. If you need to delay execution for a period of time, use the higher-level " { $link sleep } " word instead." } ;

HELP: <file-reader> "( path -- stream )"
{ $values { "path" "a string" } { "stream" "an input stream" } }
{ $description "Outputs an input stream for reading from the specified path name." }
{ $errors "Throws an error if the file is unreadable." } ;

HELP: <file-writer> "( path -- stream )"
{ $values { "path" "a string" } { "stream" "an output stream" } }
{ $description "Outputs an input stream for writing to the specified path name." }
{ $errors "Throws an error if the file is unreadable." } ;

HELP: <client> "( host port -- stream )"
{ $values { "host" "a string" } { "port" "an integer between 0 and 65535" } { "stream" "a bidirectional stream" } }
{ $description "Connects to TCP/IP port number \texttt{port} on the host named by \texttt{host}, and outputs a bidirectional stream." }
{ $errors "Throws an error if domain name lookup fails, or if there is a connection cannot be established." } ;

HELP: <server> "( port -- server )"
{ $values  { "port" "an integer between 0 and 65535" } { "server" "a handle" } }
{ $description
    "Begins listening for connections to " { $snippet "port" } " on all network interfaces. The returned object responds to two generic words:"
    { $list
        { { $link stream-close } " - stops listening on the port and frees all associated resources" }
        { { $link accept } " - blocks until there is a connection" }
    }
}
{ $errors "Throws an error if the port is already in use, or if the OS forbits access." } ;

HELP: accept "( server -- stream )"
{ $values { "server" "a handle" } { "stream" "a bidirectional stream" } }
{ $description "Waits for a connection to a server socket created by " { $link <server> } ", and outputs a bidirectional stream when the connection has been established."
$terpri
"The client socket supports two accessor words to get the host name and port number of the incoming connection:"
{ $list { $link client-stream-host } { $link client-stream-port } } }
{ $errors "Throws an error if the server socket is closed or otherwise is unavailable." } ;