Before a client can connect to a server, it must know the network address on
which the server accepts connections. Network addresses consist of a host
address or name, and a port number. Host addresses are either a string of the
VANCOUVER.SLISP.CS.CMU.EDU or a 32 bit unsigned integer. Port
numbers are 16 bit unsigned integers. Note: port in this context has
nothing to do with Mach ports and message passing.
When a process wants to receive connection requests (that is, become a
server), it first picks an integer to use as the port. Only one server
(Lisp or otherwise) can use a given port number on a given machine at
any particular time. This can be an iterative process to find a free
port: picking an integer and calling
function signals an error if the chosen port is unusable. You will
probably want to write a loop using
conditions of type error, since this function does not signal more
create-request-server sets up the current Lisp to accept
connections on the given port. If port is unavailable for any
reason, this signals an error. When a client connects to this port,
the acceptance mechanism makes a wire structure and invokes the
on-connect function. Invoking this function has a couple of
purposes, and on-connect may be
nil in which case the
system foregoes invoking any function at connect time.
The on-connect function is both a hook that allows you access
to the wire created by the acceptance mechanism, and it confirms the
connection. This function takes two arguments, the wire and the
host address of the connecting process. See the section on host
addresses below. When on-connect is
nil, the request server
allows all connections. When it is non-
nil, the function returns
two values, whether to accept the connection and a function the
system should call when the connection terminates. Either value may
nil, but when the first value is
nil, the acceptance mechanism
destroys the wire.
create-request-server returns an object that
destroy-request-server uses to terminate a connection.
destroy-request-server takes the result of
create-request-server and terminates that server. Any
existing connections remain intact, but all additional connection
attempts will fail.
connect-to-remote-server attempts to connect to a remote
server at the given port on host and returns a wire
structure if it is successful. If on-death is non-
nil, it is
a function the system invokes when this connection terminates.