More driver docs

marketplace/scribblings/drivers.scrbl

@@ -5,7 +5,138 @@
 @title{Drivers}
 
 @section{event-relay}
+
+@defmodule[marketplace/drivers/event-relay]{
+
+@defproc[(event-relay [self-id Symbol]) Spawn]{
+
+Lets processes in some @racket[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].
+
+}
+
+}
+
+@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}
+
+TODO
+
+@subsection{Accepting inbound connections}
+
+TODO
+
+@subsection{Receiving data}
+
+TODO
+
+@subsection{Sending data}
+
+TODO
+
 @section{tcp}
+
+TODO
+
 @section{timer (typed and untyped)}
+
+TODO
+
 @section{udp (typed and untyped)}
+
+TODO

marketplace/scribblings/highlevel.scrbl

@@ -15,7 +15,7 @@ the @emph{C library interface} of a Unix-like operating system. The
 @secref{low-level-interface} corresponds to the @emph{system call
 interface} of a Unix-like operating system.
 
-@section{Using @tt{#lang marketplace} and friends}
+@section[#:tag "hashlang-variations"]{Using @tt{#lang marketplace} and friends}
 
 @defmodulelang*[(marketplace
 		 marketplace/flow-control