On this page:
3.1 Connector Concepts
3.2 Connector Primitives
transport-pool/  c
3.3 Composing and Extending Connectors

3 Transport Connectors

 (require net2/connector) package: net2

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


(connector? v)  boolean?

  v : any/c
Returns #t if v is a connector.


(connector connect-proc #:custodian cust)  connector?

  connect-proc : (-> authority? (disposable/c transport?))
  cust : (make-custodian)
Returns a connector that can be used with connect to open new transports to a given authority. Calls to connect-proc, allocation of the disposable it returns, and deallocation of allocated transports are all made with cust installed as the current custodian to ensure that all ports are managed solely by the returned connector. If cust is not provided it defaults to a new custodian that is a child of the custodian that was current when connector was called.

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.


transport-pool/c : contract?

 = (disposable/c (disposable/c (transient/c transport?)))
A contract that recognizes transport pools as used by connectors. A transport pool is a collection of opened transports to a particular authority, where clients may use the transient value protocol to do any of the following:

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.


(connect! conn dest)  transport?

  conn : connector?
  dest : authority?
Connects to dest using conn and returns a transport that can be used to communicate with dest, albeit possibly with a different address for the destination authority due to name resolution. If conn opens ports or other resources managed by custodians, those resources are owned by the custodian used to construct conn instead of the current custodian. See connector for more details.

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.


(connection conn 
  #:fresh-only? fresh-only?) 
  (disposable/c (list transport? (-> void?)))
  conn : connector?
  dest : authority?
  fresh-only? : #f
Currently undocumented.

3.3 Composing and Extending Connectors


(connector-tunnel conn tunneler)  connector?

  conn : connector?
  tunneler : (-> transport? (disposable/c transport?))
Returns a connector that is like conn, except that after constructing a transport with conn (such as in a call to connect!) the tunneler procedure is used to layer a new protocol on top of the transport. This is most commonly used to convert an insecure TCP connection to a secure TLS connection with tls-transport, but other use cases exist.

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.