Re: Final(?) patch for server sockets and datagram (UDP) support.

[Kim F. Storm]

Al Petrofsky <address@hidden> writes:

> It's always been a bit confusing that emacs uses the term process for
> sockets that have no associated process.  That confusion will get a
> little worse now that emacs processes will include server and datagram
> sockets, which don't even share processes' stream-like nature.

I agree that the "tight" coupling with processes sometimes makes it
quite hard to describe the functionality in a natural way.  It would
be easier just to say "datagram socket" than "a datagram type network
process" or some such.

However, even with datagram sockets and server sockets, we still use
all (or most) of the *-process-* API functions to control, monitor,
and send and receive data on the socket, so from that POV, I found
that naming the function make-network-PROCESS was really the best
choice.

> 
> I'm not saying we should rename everything now to fix this, but I
> think it would help if the start of the "make-network-process" doc
> string immediately disclaimed any relationship to a unix process.
> 
> > :host HOST -- HOST is name of the host to connect to, or its IP
> > address.  If specified for a server process, only clients on that host
> > may connect.  The symbol `local' specifies the local host.
> 
> Don't you mean something like "If specified for a server process, it
> must be a valid name or address for the local host, and only clients
> connecting to that address will get through"?

Exactly!  Thanks for spotting this.

> 
> > :local ADDRESS -- ADDRESS is the local address used for the
> > connection.  This parameter is ignored when opening a client process.
> > When specified for a server process, the HOST and SERVICE are ignored.
> > 
> > :remote ADDRESS -- ADDRESS is the remote partner's address for the
> > connection.  This parameter is ignored when opening a server process.
> > When specified for a client process, the HOST and SERVICE are ignored.
> 
> These seemed pointless until I read the process-contact doc, and the
> NEWS.  (The format of the address wasn't documented in either
> function's doc string.)  I don't think it's a good idea to add two
> more arguments to make-network-process just so that process-contact is
> easier to document.  Is there some other point?

Instead of :family/:host/:service, you can actually use :local ADDR
when setting up a server process (when :server t is specified), and
likewise :remote ADDR to setup a client process.

I will add a description of the ADDRESS format to the doc string.

This means that if you use "clone-process" to clone a network process,
i.e. (apply 'make-network-process (process-contact old t)),
it will use the same IP addres and PORT number as the original process
(taken from :local or :remote), rather than looking up the hostname
and service again [which may in some obscure cases result in connecting
to another host or port]!

BTW, I've found a small bug related to this in my patch: When a server
process accepts a connection and creates a new process for it, it must
set the :server parameter to nil in the new process' contact list.


Here is an updated DOC string for make-network-process:

       doc: /* Create and return a network server or client process.
Input and output work as for subprocesses; `delete-process' closes it.

Arguments are specified as keyword/argument pairs.  The following
arguments are defined:

:name NAME -- NAME is name for process.  It is modified if necessary
to make it unique.

:buffer BUFFER -- BUFFER is the buffer (or buffer-name) to associate
with the process.  Process output goes at end of that buffer, unless
you specify an output stream or filter function to handle the output.
BUFFER may be also nil, meaning that this process is not associated
with any buffer.

:host HOST -- HOST is name of the host to connect to, or its IP
address.  The symbol `local' specifies the local host.  If specified
for a server process, it must be a valid name or address for the local
host, and only clients connecting to that address will be accepted.

:service SERVICE -- SERVICE is name of the service desired, or an
integer specifying a port number to connect to.  If SERVICE is t,
a random port number is selected for the server.

:family FAMILY -- FAMILY is the address (and protocol) family for the
service specified by HOST and SERVICE.  The default address family is
Inet (or IPv4) for the host and port number specified by HOST and
SERVICE.  Other address families supported are:
  local -- for a local (i.e. UNIX) address specified by SERVICE.

:local ADDRESS -- ADDRESS is the local address used for the connection.
This parameter is ignored when opening a client process. When specified
for a server process, the FAMILY, HOST and SERVICE args are ignored.

:remote ADDRESS -- ADDRESS is the remote partner's address for the
connection.  This parameter is ignored when opening a server process.
When specified for a client process, the FAMILY, HOST, and SERVICE are
ignored.

The format of ADDRESS depends on the address family:
- An IPv4 address is represented as an vector of integers [A B C D P]
corresponding to numeric IP address A.B.C.D and port number P.
- A local address is represented as a string with the address in the
local address space.
- An "unsupported family" address is represented by a cons (F . AV)
where F is the family number and AV is a vector containing the socket
address data with one element per address data byte.  Do not rely on
this format in portable code, as it may depend on implementation
defined constants, data sizes, and data structure alignment.

:datagram BOOL -- Create a datagram type connection if BOOL is
non-nil.  Default is a stream type connection.

:nowait BOOL -- If BOOL is non-nil for a stream type client process,
return without waiting for the connection to complete; instead, the
sentinel function will be called with second arg matching "open" (if
successful) or "failed" when the connect completes.  Default is to use
a blocking connect (i.e. wait) for stream type connections.

:noquery BOOL -- Query the user unless BOOL is non-nil, and process is
running when emacs is exited.

:stop BOOL -- Start process in the `stopped' state if BOOL non-nil.
In the stopped state, a server process does not accept new
connections, and a client process does not handle incoming traffic.
The stopped state is cleared by `continue-process' and set by
`stop-process'.

:filter FILTER -- Install FILTER as the process filter.

:sentinel SENTINEL -- Install SENTINEL as the process sentinel.

:log LOG -- Install LOG as the server process log function.  This
function is called as when the server accepts a network connection from a
client.  The arguments are SERVER, CLIENT, and MESSAGE, where SERVER
is the server process, CLIENT is the new process for the connection,
and MESSAGE is a string.

:server BOOL -- if BOOL is non-nil, create a server process for the
specified FAMILY, SERVICE, and connection type (stream or datagram).
Default is a client process.

A server process will listen for and accept connections from
clients.  When a client connection is accepted, a new network process
is created for the connection with the following parameters: 
- The client's process name is constructed by concatenating the server
process' NAME and a client identification string.
- If the FILTER argument is non-nil, the client process will not get a
separate process buffer; otherwise, the client's process buffer is a newly
created buffer named after the server process' BUFFER name or process
NAME concatenated with the client identification string.  
- The connection type and the process filter and sentinel parameters are
inherited from the server process' TYPE, FILTER and SENTINEL.
- The client process' contact info is set according to the client's
addressing information (typically an IP address and a port number).

Notice that the FILTER and SENTINEL args are never used directly by
the server process.  Also, the BUFFER argument is not used directly by
the server process, but via `network-server-log-function' hook, a log
of the accepted (and failed) connections may be recorded in the server
process' buffer.

The following special call returns t iff a given KEY VALUE
pair is supported on this system:
  (make-network-process :feature KEY VALUE)  */)

-- 
Kim F. Storm <address@hidden> http://www.cua.dk