100 lines
4.5 KiB
Racket
100 lines
4.5 KiB
Racket
#lang scribble/doc
|
|
@(require "common.rkt"
|
|
(for-label mzlib/thread
|
|
racket/engine
|
|
scheme/contract
|
|
scheme/tcp))
|
|
|
|
@mzlib[#:mode title thread]
|
|
|
|
@deprecated[@racketmodname[racket/engine]]{}
|
|
|
|
Re-exports the bindings from @racketmodname[racket/engine] under
|
|
different names and also provides two extra bindings. The renamings
|
|
are:
|
|
|
|
@itemlist[
|
|
@item{@racket[engine] as @racket[coroutine]}
|
|
@item{@racket[engine?] as @racket[coroutine?]}
|
|
@item{@racket[engine-run] as @racket[coroutine-run]}
|
|
@item{@racket[engine-result] as @racket[coroutine-result]}
|
|
@item{@racket[engine-kill] as @racket[coroutine-kill]}
|
|
]
|
|
|
|
@defproc[(consumer-thread [f procedure?][init (-> any) void])
|
|
(values thread? procedure?)]{
|
|
|
|
Returns two values: a thread descriptor for a new thread, and a
|
|
procedure with the same arity as @racket[f].
|
|
|
|
When the returned procedure is applied, its arguments are queued to be
|
|
passed on to @racket[f], and @|void-const| is immediately returned.
|
|
The thread created by @racket[consumer-thread] dequeues arguments and
|
|
applies @racket[f] to them, removing a new set of arguments from the
|
|
queue only when the previous application of @racket[f] has completed;
|
|
if @racket[f] escapes from a normal return (via an exception or a
|
|
continuation), the @racket[f]-applying thread terminates.
|
|
|
|
The @racket[init] argument is a procedure of no arguments; if it is
|
|
provided, @racket[init] is called in the new thread immediately after the
|
|
thread is created.}
|
|
|
|
|
|
@defproc[(run-server [port-no (integer-in 1 65535)]
|
|
[conn-proc (input-port? output-port? . -> . any)]
|
|
[conn-timeout (and/c real? (not/c negative?))]
|
|
[handler (exn? . -> . any/c) void]
|
|
[listen ((integer-in 1 65535) (one-of/c 5) (one-of/c #t)
|
|
. -> . listener?)
|
|
tcp-listen]
|
|
[close (listener? . -> . any) tcp-close]
|
|
[accept (listener? . ->* . (input-port? output-port?)) tcp-accept]
|
|
[accept/break (listener? . ->* . (input-port? output-port?)) tcp-accept/enable-break])
|
|
void?]{
|
|
|
|
Executes a TCP server on the port indicated by @racket[port-no]. When
|
|
a connection is made by a client, @racket[conn] is called with two
|
|
values: an input port to receive from the client, and an output port
|
|
to send to the client.
|
|
|
|
Each client connection is managed by a new custodian, and each call to
|
|
@racket[conn] occurs in a new thread (managed by the connection's
|
|
custodian). If the thread executing @racket[conn] terminates for any
|
|
reason (e.g., @racket[conn] returns), the connection's custodian is
|
|
shut down. Consequently, @racket[conn] need not close the ports
|
|
provided to it. Breaks are enabled in the connection thread if breaks
|
|
are enabled when @racket[run-server] is called.
|
|
|
|
To facilitate capturing a continuation in one connection thread and
|
|
invoking it in another, the parameterization of the
|
|
@racket[run-server] call is used for every call to
|
|
@racket[handler]. In this parameterization and for the connection's
|
|
thread, the @racket[current-custodian] parameter is assigned to the
|
|
connection's custodian.
|
|
|
|
If @racket[conn-timeout] is not @racket[#f], then it must be a
|
|
non-negative number specifying the time in seconds that a connection
|
|
thread is allowed to run before it is sent a break signal. Then, if
|
|
the thread runs longer than @racket[(* conn-timeout 2)] seconds, then
|
|
the connection's custodian is shut down. If @racket[conn-timeout] is
|
|
@racket[#f], a connection thread can run indefinitely.
|
|
|
|
If @racket[handler] is provided, it is passed exceptions related
|
|
to connections (i.e., exceptions not caught by @racket[conn-proc], or
|
|
exceptions that occur when trying to accept a connection). The default
|
|
handler ignores the exception and returns @|void-const|.
|
|
|
|
The @racket[run-server] function uses @racket[listen], @racket[close],
|
|
@racket[accept] and @racket[accept/break] in the same way as it might
|
|
use @racket[tcp-listen], @racket[tcp-close], @racket[tcp-accept], and
|
|
@racket[tcp-accept/enable-break] to accept connections. Provide
|
|
alternate procedures to use an alternate communication protocol (such
|
|
as SSL) or to supply optional arguments in the use of
|
|
@racket[tcp-listen]. The @racket[listener?] part of the contract
|
|
indicates that the procedures must all work on the same kind of
|
|
listener value.
|
|
|
|
The @racket[run-server] procedure loops to serve client connections,
|
|
so it never returns. If a break occurs, the loop will cleanly shut
|
|
down the server, but it will not terminate active connections.}
|