neon/tcp

Types

ConnectOptions

opaque </>

Options for establishing a TCP connection.

Create with new, then optionally configure with ip_version and timeout before passing to connect.

pub opaque type ConnectOptions

Tcp

</>

A TCP socket.

pub type Tcp

TcpError

</>

Errors that can occur during TCP operations.

pub type TcpError {
  Closed
  Timeout
  SystemLimit
  NotOwner
  InvalidPid
  Posix(net.Posix)
  TcpError(String)
}

Constructors

```
Closed
```
The connection was closed.
```
Timeout
```
The operation timed out.
```
SystemLimit
```
The Erlang VM can’t allocate more resources for network operations.
```
NotOwner
```
The calling process is not the current owner of the socket.
```
InvalidPid
```
The target pid is not alive.
```
Posix(net.Posix)
```
A POSIX error.
```
TcpError(String)
```
A generic TCP error with a description.

TcpMessage

</>

Messages received from a TCP socket.

pub type TcpMessage {
  Packet(Tcp, BitArray)
  SocketClosed(Tcp)
  SocketError(Tcp, TcpError)
}

Constructors

```
Packet(Tcp, BitArray)
```
Data received from the socket.
```
SocketClosed(Tcp)
```
The socket was closed.
```
SocketError(Tcp, TcpError)
```
An error occurred on the socket.

Values

accept

</>

pub fn accept(
  socket: Tcp,
  timeout: net.Timeout,
) -> Result(Tcp, TcpError)

Accepts an incoming connection on a listening socket.

Blocks until a connection arrives or the timeout expires.

active

</>

pub fn active(socket: Tcp) -> Result(Tcp, TcpError)

Sets the socket to active mode.

In active mode, incoming data is delivered as messages to the socket owner’s mailbox. Use select to handle these messages.

close

</>

pub fn close(socket: Tcp) -> Nil

Closes a TCP socket.

This function is idempotent and always returns Nil.

connect

</>

pub fn connect(opts: ConnectOptions) -> Result(Tcp, TcpError)

Establishes a TCP connection using the given options.

controlling_process

</>

pub fn controlling_process(
  socket: Tcp,
  pid: process.Pid,
) -> Result(Nil, TcpError)

Change the controlling process of a socket.

The controlling process is the process that the socket sends messages to.

ip_version

</>

pub fn ip_version(
  opts: ConnectOptions,
  ip_version: net.IpVersion,
) -> ConnectOptions

Sets the IP version for the connection.

listen

</>

pub fn listen(
  port: net.Port,
  ip_address: net.IpAddress,
) -> Result(Tcp, TcpError)

Creates a listening TCP socket bound to the given port and IP address.

new

</>

pub fn new(
  address: net.Address,
  port: net.Port,
) -> ConnectOptions

Creates connection options for the given address and port.

Defaults to IPv4 if the address is a net.hostname. Default timeout is set to infinity.

passive

</>

pub fn passive(socket: Tcp) -> Result(Tcp, TcpError)

Sets the socket to passive mode.

In passive mode, data must be read explicitly using receive.

port

</>

pub fn port(socket: Tcp) -> Result(net.Port, Nil)

Returns the port number assigned to a socket by the operating system.

Useful when listening on port 0 (OS-assigned).

receive

</>

pub fn receive(
  socket: Tcp,
  length: Int,
  timeout: net.Timeout,
) -> Result(BitArray, TcpError)

Receives data from a TCP socket.

The length parameter specifies the number of bytes to receive. Use 0 to receive whatever data is available. Must be non-negative.

select

</>

pub fn select(
  selector: process.Selector(t),
  mapper: fn(TcpMessage) -> t,
) -> process.Selector(t)

Adds TCP message handlers to a selector for use with active mode sockets.

In active mode, incoming data, close notifications, and errors are delivered as messages to the socket owner’s mailbox. Use this function to register handlers for these messages on a Selector.

send

</>

pub fn send(
  socket: Tcp,
  payload: BitArray,
) -> Result(Nil, TcpError)

Sends data over a TCP socket.

shutdown

</>

pub fn shutdown(socket: Tcp) -> Result(Nil, TcpError)

Shuts down the socket for both reading and writing.

timeout

</>

pub fn timeout(
  opts: ConnectOptions,
  timeout: net.Timeout,
) -> ConnectOptions

Sets the connection timeout.