9.9 gauche.connection - Connection framework ¶

Module: gauche.connection ¶

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.

The <socket> class, for example, implements the connection framework (see gauche.net - 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 connection-address-name method to get its string representation, so that can be used for logging and monitoring. The concrete class can choose suitable address representation. For example, <socket> uses <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 concrete implementation. Each concrete implementation should provide its own procedure to create and return a new connection.

Method: connection-self-address connection ¶

Method: connection-peer-address connection ¶

{gauche.connection} Returns the address of this connection’s endpoint and its peer’s. For sockets and <tls>, it is an instance of <sockaddr>. For processes, it is a string describing the process.

If connection is not connected, these methods can return #f.

The returned value (other than #f) must be able to be passed to connection-address-name method.

Currently addresses are only used for logging purpose 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.

Method: connection-address-name address ¶

{gauche.connection} This method returns a string representation of address, which is a returned value from connection-self-address and connection-peer-address. It is for display/logging. For sockets, a resonable string representation of socket address is returned. The default method just uses address’s display-representation. If a concrete class chooses aggregate objects to represent addresses, it should provide this method as well.

Method: connection-input-port connection ¶

Method: connection-output-port connection ¶

{gauche.connection} Returns an input port and an output port of the connection, respectively. Writing to the output port sends the data to the peer, and reading from the input port returns the received data.

If the connection is not connected, or already shutdown or closed, the return value of these methods are unspecified.

Method: connection-shutdown connection :optional how ¶

{gauche.connection} 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:

read

Shutdown read channel of the connection.

write

Shutdown write channel of the connection.

both

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.

Method: connection-close connection ¶

{gauche.connection} Close the connection. This destroys the connection and frees local resources. Note that this does not shutdown the connection itself. For example, when a process forks after establishing a connection and the parent process closes the connection, the child process can still communicate with the connection.

If this connection is the only endpoint of this side, the peer will get an error when it tries to communicate.

See connection-shutdown for the details of shutting down a connection.