Networking

MzScheme provides a minimal collection of TCP-based communication procedures.

• (tcp-listen port-number [max-allow-wait]) creates a ``listening'' server on the local machine at the specified port number (where port-number is an exact integer between 1 and 65535). The max-allow-wait argument determines the maximum number of client connections that can be waiting for acceptance. (When max-allow-wait clients are waiting acceptance, no new client connections can be made.) The default value for max-allow-wait argument is 4.

  The return value of tcp-listen is a TCP listener value. This value can be used in future calls to tcp-accept, tcp-accept-ready?, and tcp-close. Each new TCP listener value is placed into the management of the current custodian (see section 9.5).

  If the server cannot be started by tcp-listen, the exn:i/o:tcp:listen exception is raised.

• (tcp-connect hostname port-number) attempts to connect as a client to a listening server. The hostname argument is a string for the server host's internet address name (e.g., "cs.rice.edu"), and port-number (an exact integer between 1 and 65535) is the port where the server is listening.

  Two values (see Chapter 2) are returned by tcp-connect: an input port and an output port. Data can be received from the server through the input port and sent to the server through the output port. If the server is a MzScheme process, it can obtain ports to communicate to the client with tcp-accept. These ports are placed into the management of the current custodian (see section 9.5).

  The client input and output ports are not independent: closing the output port does not cause the server to receive an end-of-file. Instead, both ports must be closed before the server receieves an end-of-file.

  If a connection cannot be established by tcp-connect, the exn:i/o:tcp:connect exception is raised.

• (tcp-accept listener) accepts a client connection for the server associated with listener. The listener argument is a TCP listener value returned by tcp-listen. If no client connection is waiting on the listening port, the call to tcp-accept will block. (See also tcp-accept-ready?, below.)

  Two values (see Chapter 2) are returned by tcp-accept: an input port and an output port. Data can be received from the client through the input port and sent to the client through the output port. These ports are placed into the management of the current custodian (see section 9.5).

  The accepted input and output ports are not independent: closing the output port does not cause the client's input port to receive and end-of-file. Instead, both ports must be closed before the client receieves an end-of-file.

  If a connection cannot be accepted by tcp-accept, the exn:i/o:tcp:accept exception is raised. If the listener has been closed, the exn:i/o:tcp:listener-closed exception is raised.

• (tcp-accept-ready? listener) tests whether an unaccepted client has connected to the server associated with listener. The listener argument is a TCP listener value returned by tcp-listen. If a client is waiting, the return value is #t, otherwise it is #f. A client is accepted with the tcp-accept procedure, which returns ports for communicating with the client and removes the client from the list of unaccepted clients.

  If the listener has been closed, the exn:i/o:tcp:listener-closed exception is raised.

• (tcp-close listener) shuts down the server associated with listener. The listener argument is a TCP listener value returned by tcp-listen. All unaccepted clients receive an end-of-file from the server; connections to accepted clients are unaffected.

  If the listener has already been closed, the exn:i/o:tcp:listener-closed exception is raised.

• (tcp-listener? v) returns #t if v is a TCP listener value created by tcp-listen, #f otherwise.
• (tcp-port-send-waiting? p) tests whether the low-level send buffer for the TCP output port p is full. If the low-level buffer is full, #t is returned, otherwise #f is returned. (A #f return value does not indicate that all data has been sent or received.)

  This procedure is provided because MzScheme automatically buffers data written to a TCP output port. Stream-based applications can use this procedure to detect excessive output buffering.