Thousand Island v0.2.0 ThousandIsland.Transport behaviour View Source

This module describes the behaviour required for Thousand Island to interact with low-level sockets. It is largely internal to Thousand Island, however users are free to implement their own versions of this behaviour backed by whatever underlying transport they choose. Such a module can be used in Thousand Island by passing its name as the transport_module option when starting up a server, as described in ThousandIsland.

Link to this section Summary

Types

A listener socket used to wait for connections

The return value from a recv/3 call

A socket representing a client connection

Information about an endpoint (either remote ('peer') or local

Options which can be set on a socket via setopts/2

The direction in which to shutdown a connection in advance of closing it

Callbacks

Wait for a client connection on the given listener socket. This call blocks until such a connection arrives, or an error occurs (such as the listener socket being closed).

Closes the given socket.

Transfers ownership of the given socket to the given process. This will always be called by the process which currently owns the socket.

Performs an initial handshake on a new client connection (such as that done when negotiating an SSL connection). Transports which do not have such a handshake can simply pass the socket through unchanged.

Create and return a listener socket bound to the given port and configured per the provided options.

Return the local port number that the given listener socket is accepting connections on.

Returns information in the form of t:socket_info() about the local end of the socket.

Returns information in the form of t:socket_info() about the remote end of the socket.

Returns available bytes on the given socket. Up to num_bytes bytes will be returned (0 can be passed in to get the next 'available' bytes, typically the next packet). If insufficient bytes are available, the functino can wait timeout milliseconds for data to arrive.

Sends the given data (specified as a binary or an IO list) on the given socket.

Sends the contents of the given file based on the provided offset & length

Sets the given options on the socket. Should disallow setting of options which are not compatible with Thousand Island

Shuts down the socket in the given direction.

Link to this section Types

A listener socket used to wait for connections

Link to this type

on_recv()

View Source
on_recv() :: {:ok, binary()} | {:error, String.t()}

The return value from a recv/3 call

A socket representing a client connection

Link to this type

socket_info()

View Source
socket_info() :: %{address: String.t(), port: :inet.port_number()}

Information about an endpoint (either remote ('peer') or local

Link to this type

socket_options()

View Source
socket_options() :: [:inet.socket_setopts()]

Options which can be set on a socket via setopts/2

Link to this type

way()

View Source
way() :: :read | :write | :read_write

The direction in which to shutdown a connection in advance of closing it

Link to this section Callbacks

Link to this callback

accept(listener_socket)

View Source
accept(listener_socket()) :: {:ok, socket()} | {:error, any()}

Wait for a client connection on the given listener socket. This call blocks until such a connection arrives, or an error occurs (such as the listener socket being closed).

Closes the given socket.

Link to this callback

controlling_process(socket, pid)

View Source
controlling_process(socket(), pid()) :: :ok | {:error, any()}

Transfers ownership of the given socket to the given process. This will always be called by the process which currently owns the socket.

Link to this callback

handshake(socket)

View Source
handshake(socket()) :: {:ok, socket()} | {:error, any()}

Performs an initial handshake on a new client connection (such as that done when negotiating an SSL connection). Transports which do not have such a handshake can simply pass the socket through unchanged.

Create and return a listener socket bound to the given port and configured per the provided options.

Link to this callback

listen_port(listener_socket)

View Source
listen_port(listener_socket()) :: {:ok, :inet.port_number()}

Return the local port number that the given listener socket is accepting connections on.

Link to this callback

local_info(socket)

View Source
local_info(socket()) :: socket_info()

Returns information in the form of t:socket_info() about the local end of the socket.

Link to this callback

peer_info(socket)

View Source
peer_info(socket()) :: socket_info()

Returns information in the form of t:socket_info() about the remote end of the socket.

Link to this callback

recv(socket, num_bytes, timeout)

View Source
recv(socket(), num_bytes :: non_neg_integer(), timeout :: timeout()) ::
  on_recv()

Returns available bytes on the given socket. Up to num_bytes bytes will be returned (0 can be passed in to get the next 'available' bytes, typically the next packet). If insufficient bytes are available, the functino can wait timeout milliseconds for data to arrive.

Link to this callback

send(socket, data)

View Source
send(socket(), data :: IO.iodata()) :: :ok | {:error, String.t()}

Sends the given data (specified as a binary or an IO list) on the given socket.

Link to this callback

sendfile(socket, filename, offset, length)

View Source
sendfile(
  socket(),
  filename :: String.t(),
  offset :: non_neg_integer(),
  length :: non_neg_integer()
) :: {:ok, non_neg_integer()} | {:error, String.t()}

Sends the contents of the given file based on the provided offset & length

Link to this callback

setopts(socket, socket_options)

View Source
setopts(socket(), socket_options()) :: :ok | {:error, String.t()}

Sets the given options on the socket. Should disallow setting of options which are not compatible with Thousand Island

Link to this callback

shutdown(socket, way)

View Source
shutdown(socket(), way()) :: :ok

Shuts down the socket in the given direction.