gauche.connection- Connection framework
A connection is an abstract class to handle full-duplex communication channel. The actual data I/O is done through Scheme ports; a channel provides an interface to retrieve those ports. It also has interface to know endpoint names, and the way to shutdown the communication.
<socket> class, for example, implements the connection
framework (see Networking). The
<tls> class, which
wraps a socket to provide TLS communication, also implements it.
That means you can write a client code that works both plain
socket connection and secure connection.
You can also abstract communication to the external process
as a connection (see Process connection).
Each of the connection endpoints (self for our side,
and peer fo the other side) has addresses,
some object that identifies the endpoint. The framework
doesn’t specify the actual type of addresses; it only requires
that addresses can be passed to
to get its string representation, so that can be used for logging
and monitoring. The concrete
class can choose suitable address representation. For example,
<sockaddr> for the addresses.
A concrete class must implement the following methods.
connection-self-address (c <connection>) connection-peer-address (c <connection>) connection-input-port (c <connection>) connection-output-port (c <connection>) connection-shutdown (c <connection>) how connection-close (c <connection>) connection-address-name obj ; optional
At this moment this framework doesn’t provide a generic way to create a connection, since the way to do it may greatly vary depending on the concreate implementation. Each concrete implementation should provide its own procedure to create and return a new connection.
Returns the address of this connection’s endpoint and
its peer’s. For sockets and
<tls>, it is an instance
<sockaddr>. For processes, it is a string
describing the process.
If connection is not connected, these methods can return
The returned value (other than
#f) must be able to
be passed to
Currently addresses are only used for logging purpoes within the connection framework; however, we may enhance the framework to add “connect” operation, for example, so the concrete class is encouraged to use objects that can be used to create connections.
This method returns a string representation of address, which is
a returned value from
connection-peer-address. The default method just uses
display-representation. If a concrete
class chooses aggregate objects to represent addresses, it should
provide this method as well.
Returns an input port and an output port to read from and write to the connection, respectively.
If the connection is not connected, or already shutdown or closed, the return value of these methods are unspecified.
Shutdown the connection. You can either shutdown the connection entirely at once, or shutdown only read or write channel of it.
Shutdown is about telling the peer to terminate the communication. Usually the peer will detect the termination by reading EOF from their input channel. The port corresponding to the shutdown channel is closed so no further communication is possible.
Note that merely closing the connection doesn’t shutdown the connection—the process may fork after creating the connection, and in that case, one process may close the connection without shutting down.
The how argument must be one of those symbols:
Shutdown read channel of the connection.
Shutdown write channel of the connection.
Shutdown both channels of the connection.
If omitted, both is assumed.
Shutting down already shut down channel has no effect.
Note: Some concrete implementation of connection may not allow to shutdown each channels independently. In such case, the connection is shut down entirely regardless of how argument.
The one-argument case is handled by the default method (it calls
two-argument method with
both as how). So the
concrete class only need to define two argument method.
Close the connection. This destroys the connection and frees local resources. Note that this does not shutdown the connection itself. If this connection is the only endpoint of this side, the peer will get an error when it tries to communicate.
connection-shutdown for the details of shutting down