219 lines
6.6 KiB
Racket
219 lines
6.6 KiB
Racket
#lang scribble/manual
|
|
@require[racket/include]
|
|
@include{prelude.inc}
|
|
|
|
@require[(for-label marketplace/drivers/event-relay
|
|
marketplace/drivers/tcp-bare)]
|
|
|
|
@title{Drivers}
|
|
|
|
@section{event-relay}
|
|
|
|
@defmodule[marketplace/drivers/event-relay]{
|
|
|
|
@defproc[(event-relay [self-id Symbol]) Spawn]{
|
|
|
|
Lets processes in some nested VM interact with the outside
|
|
world using @racket[ground-vm]-level event-based subscriptions.
|
|
|
|
Returns a @racket[spawn] which starts an event-relay process with
|
|
debug-name @racket[`(event-relay ,self-id)].
|
|
|
|
The relay process observes subscriptions matching the topic-pattern
|
|
@racket[(cons (? evt?) _)], and when one appears, constructs an
|
|
analogous one using @racket[at-meta-level] to connect to the next VM
|
|
down the stack. Messages from the meta-level will be relayed up to the
|
|
current level. When the subscription disappears, the relay withdraws
|
|
the subscription at the meta-level as well.
|
|
|
|
}
|
|
|
|
}
|
|
|
|
@section{tcp-bare}
|
|
|
|
@defmodule[marketplace/drivers/tcp-bare]{
|
|
|
|
This module is only available for use by untyped Racket processes. It
|
|
is included by default in programs using @tt{#lang marketplace}; see
|
|
@secref{hashlang-variations} for information on other language
|
|
variants.
|
|
|
|
@defproc[(tcp-driver) Spawn]{
|
|
|
|
Returns a @racket[spawn] action which starts a TCP driver. The TCP
|
|
driver should run either directly in a ground VM, or in a nested VM
|
|
with a running @racket[event-relay].
|
|
|
|
}
|
|
|
|
@defthing[tcp Spawn]{
|
|
|
|
A pre-made @racket[spawn] action equivalent to @racket[(tcp-driver)].
|
|
|
|
}
|
|
|
|
}
|
|
|
|
@subsection{TCP channels}
|
|
|
|
@defstruct*[tcp-channel ([source TcpAddress]
|
|
[destination TcpAddress]
|
|
[subpacket TcpSubPacket]) #:prefab]{
|
|
|
|
A TCP channel represents a section of a unidirectional TCP flow
|
|
appearing on our local "subnet" of the full TCP network, complete with
|
|
source, destination and subpacket. Each TCP connection has two such
|
|
flows: one inbound (remote-to-local) bytestream, and one outbound
|
|
(local-to-remote) bytestream.
|
|
|
|
}
|
|
|
|
@deftype[TcpSubPacket (or/c eof-object? bytes?)]{
|
|
|
|
Packets carried by @racket[tcp-channel] structures are either
|
|
end-of-file objects or raw binary data represented as Racket byte
|
|
vectors.
|
|
|
|
}
|
|
|
|
@subsection{TCP addresses}
|
|
|
|
@deftype[TcpAddress (or/c tcp-address? tcp-handle? tcp-listener?)]{
|
|
|
|
A TCP address describes one end of a TCP connection. It can be either
|
|
|
|
@itemlist[
|
|
@item{a @racket[tcp-address], representing a remote socket;}
|
|
@item{a @racket[tcp-handle], representing a local socket on a kernel-assigned port; or}
|
|
@item{a @racket[tcp-listener], representing a local socket on a user-assigned port.}
|
|
]
|
|
|
|
}
|
|
|
|
@defstruct*[tcp-address ([host string?]
|
|
[port (integer-in 0 65535)]) #:prefab]{
|
|
|
|
Describes a remote half-connection. The @racket[host] part is to be a
|
|
string containing either a hostname (e.g. @racket["localhost"]) or an
|
|
ASCII representation of an IP address (e.g. @racket["127.0.0.1"]).
|
|
|
|
}
|
|
|
|
@defstruct*[tcp-handle ([id any/c]) #:prefab]{
|
|
|
|
Describes a local half-connection with a kernel-assigned port number.
|
|
The port number is not directly accessible; the @racket[id] is used as
|
|
a local name for whichever underlying port number ends up being used.
|
|
|
|
The @racket[id] must be chosen carefully: it is scoped to the local
|
|
VM, i.e. shared between processes in that VM, so processes must make
|
|
sure not to accidentally clash in handle ID selection. They are also
|
|
used in TcpChannel to mean a specific @emph{instance} of a TCP
|
|
connection, so if you are likely to want to reconnect individual
|
|
flows, use different values for @racket[id].
|
|
|
|
}
|
|
|
|
@defstruct*[tcp-listener ([port (integer-in 0 65535)]) #:prefab]{
|
|
|
|
Describes a local half-connection with a user-assigned port number.
|
|
Use this to describe server sockets.
|
|
|
|
}
|
|
|
|
@subsection{Opening an outbound connection}
|
|
|
|
Choose a @racket[tcp-handle], and then create endpoints as follows:
|
|
|
|
@racketblock[
|
|
(let ((local (tcp-handle 'some-unique-value))
|
|
(remote (tcp-address "the.remote.host.example.com" 5999)))
|
|
(transition/no-state
|
|
(publisher (tcp-channel local remote ?))
|
|
(subscriber (tcp-channel remote local ?)
|
|
(on-message
|
|
[(tcp-channel _ _ (? eof-object?))
|
|
(code:comment "Handle a received end-of-file object")
|
|
(transition ...)]
|
|
[(tcp-channel _ _ (? bytes? data))
|
|
(code:comment "Handle received data")
|
|
(transition ...)]))))
|
|
]
|
|
|
|
The TCP driver will automatically create an outbound connection in
|
|
response to the presence of the endpoints. When the endpoints are
|
|
deleted (or the process exits), the TCP driver will notice the absence
|
|
and will close the underlying TCP socket.
|
|
|
|
For a complete example, see @secref{chat-client-example}.
|
|
|
|
@subsection{Accepting inbound connections}
|
|
|
|
Choose a port number, and then create an @emph{observer} endpoint as
|
|
follows:
|
|
|
|
@racketblock[
|
|
(observe-publishers (tcp-channel ? (tcp-listener 5999) ?)
|
|
(match-conversation (tcp-channel them us _)
|
|
(on-presence (spawn (chat-session them us)))))
|
|
]
|
|
|
|
The use of @racket[observe-publishers] here indicates that this endpoint isn't
|
|
actually interested in exchanging any TCP data; instead, it is
|
|
monitoring demand for such exchanges. The TCP driver uses the unusual
|
|
@racket['everything] @racket[InterestType] to monitor the presence of
|
|
@racket['observer]s, and creates listening TCP server sockets in
|
|
response. When a connection comes in, the TCP driver spawns a manager
|
|
process which offers regular @racket['participant] endpoints for
|
|
communicating on the newly-arrived socket.
|
|
|
|
To illustrate the code for handling a newly-arrived connection,
|
|
|
|
@racketblock[
|
|
(define (chat-session them us)
|
|
(transition/no-state
|
|
(subscriber (tcp-channel them us ?)
|
|
(on-absence (quit))
|
|
(on-message [(tcp-channel _ _ (? bytes? data))
|
|
(code:comment "Handle incoming data")
|
|
(transition ...)]))))
|
|
]
|
|
|
|
@subsection{Receiving data}
|
|
|
|
TCP-related messages will be of the form
|
|
|
|
@racketblock[(tcp-channel remote-address local-address subpacket)]
|
|
|
|
where the @racket[subpacket] is either @racket[eof] or a
|
|
@racket[bytes?].
|
|
|
|
@subsection{Sending data}
|
|
|
|
Send data with
|
|
|
|
@racketblock[(send-message (tcp-channel local-address remote-address subpacket))]
|
|
|
|
where, as for receiving data, the @racket[subpacket] is either
|
|
@racket[eof] or a @racket[bytes?].
|
|
|
|
@;{
|
|
@section{tcp}
|
|
Not yet documented.
|
|
}
|
|
|
|
@section{timer (typed and untyped)}
|
|
|
|
For examples of the use of the timer driver, see uses of
|
|
@racket[set-timer] and @racket[timer-expired] in
|
|
@hyperlink["https://github.com/tonyg/marketplace-dns/blob/master/network-query.rkt"]{the
|
|
Marketplace-based DNS resolver}.
|
|
|
|
@section{udp (typed and untyped)}
|
|
|
|
For examples of the use of the UDP driver, see uses of
|
|
@racket[udp-packet] etc. in
|
|
@hyperlink["https://github.com/tonyg/marketplace-dns/blob/master/tk-dns.rkt"]{the
|
|
Marketplace-based DNS resolver}.
|