3 Transport Connectors

A connector is a means of opening new transports to arbitrary authorities. Connectors play the role of a "client" authority in the sense that they send connection requests to "server" authorities, but once an authority accepts that request and opens a new transport either party may send or receive bytes to the other at any time. To instead accept connection requests from others, see listeners.

The net2/connector module defines a means of constructing new connectors as well as generic ways of extending connectors. For connectors that use the operating system’s networking including TCP connectors, see the net2/system module.

3.1 Connector Concepts

Connectors are typically responsible for all connections of a specific kind in a program, regardless of which thread attempts to connect to which authority. This allows connectors to reuse connections across threads without fear that a custodian shutdown in one thread will close a transport used by another thread. Connector transport reuse and management is primarily defined in terms of disposables from the disposable library.

Note that many kinds of transports (including TCP connections) are expensive to create, maintain, and terminate. It is crucial to minimize the number of open connections between two parties, but sometimes higher-level protocols need to control when connections are closed or whether a fresh, previously unused connection is required. For this purpose, connectors are defined in terms of transport pools. A transport pool is a combination of a disposable pool and a transient that allows reusing transports, and is defined by the transport-pool/c contract.

3.2 Connector Primitives

The connect-proc procedure is expected to choose a source authority for outgoing transports, as well as resolve the destination authority from a resolvable name authority (such as a DNS address) to a more direct network address authority (such as an IP address). As a result, transports created by connect-proc may have a different destination authority than the destination authority oringally provided to connect-proc.

Cleanly closing transports may involve negotiating shutdown actions with the destination authority. The disposable returned by connect-proc is expected to responsibly implement this sort of graceful close logic, with forceful termination of the transport left to custodian shutdowns and finalizers. See Transport Cleanup and Disposables for a more in-depth discussion.

• Get any open transport — creating a new one if one doesn’t exist — and return it to the pool after use.

• Open a fresh transport that’s never been used and return it to the pool after use.

• Explicitly close a transport ensuring that it won’t be used again.

Most clients will simply request any available transport and return it after use, but some protocols require clients explicitly close connections after specific interactions. The use of transient values offers clients a mechanism for opting-in to this complexity, even when other clients of the same pool choose the simpler interface.

The returned transport is created for use only in the current thread and automatically destroyed when the current thread dies, but the meaning of "destroyed" is dependent on the specific connector used. In particular, some connectors may reuse transports in the future. For precise control over construction and destruction of transports, see the connection procedure.

3.3 Composing and Extending Connectors

The disposable returned by tunneler is responsible only for setting up and tearing down the new protocol on top of an already existing transport — it is not responsible for creating or destroying the underlying transport being tunneled over. As a consequence, this allows opening and closing a tunnel multiple times on the same transport if conn reuses transports. To control whether or not a tunnel should use a fresh transport, see the connection procedure.

Tunnel disposables are not expected to created new ports or other custodian managed resources due to their reuse of an existing transport, but in the event one does they will be created under supervision of a new custodian that is subordinate to the custodian of conn, not the current custodian.