Provides a high-level interface for starting and managing Thousand Island server instances. Server instances exist as a process tree, which is usually started by starting this module's child spec within an existing supervision tree, or by calling start_link/1 directly.

Examples

A typical use of ThousandIsland might look like the following:

defmodule MyApp.Supervisor do
  # ... other Supervisor boilerplate

  def init(config) do
    children = [
      # ... other children as dictated by your app
      {ThousandIsland, port: 1234, handler_module: MyApp.ConnectionHandler}
    ]

    Supervisor.init(children, strategy: :one_for_one)
  end
end

You can also start servers directly via the start_link/1 function:

{:ok, pid} = ThousandIsland.start_link(port: 1234, handler_module: MyApp.ConnectionHandler)

Configuration

A number of options are defined when starting a server. The complete list is defined by the t:options() type.

Logging & Telemetry

As a low-level library, Thousand Island purposely does not do any inline logging of any kind. The ThousandIsland.Logging module defines a number of functions to aid in tracing connections at various log levels, and such logging can be dynamically enabled and disabled against an already running server. This logging is backed by :telemetry events internally, and if desired these events can also be hooked by your application for logging or metric purposes. The following is a complete list of events emitted by Thousand Island:

• [:listener, :start]: Emitted when the server successfully listens on the configured port.
• [:listener, :error]: Emitted when the server encounters an error listening on the configured port.
• [:listener, :shutdown]: Emitted when the server shuts down.
• [:acceptor, :start]: Emitted when an acceptor process starts up.
• [:acceptor, :accept]: Emitted when an acceptor process accepts a new client connection.
• [:acceptor, :shutdown]: Emitted when an acceptor process shuts down.
• [:handler, :start]: Emitted whenever a ThousandIsland.Handler process is made ready
• [:handler, :async_recv]: Emitted whenever a ThousandIsland.Handler process receives data asynchronously
• [:handler, :shutdown]: Emitted whenever a ThousandIsland.Handler process terminates
• [:handler, :error]: Emitted whenever a ThousandIsland.Handler process shuts down due to error
• [:socket, :handshake]: Emitted whenever a ThousandIsland.Socket.handshake/1 call completes.
• [:socket, :handshake_error]: Emitted whenever a ThousandIsland.Socket.handshake/1 call errors.
• [:socket, :recv]: Emitted whenever a ThousandIsland.Socket.recv/3 call completes.
• [:socket, :send]: Emitted whenever a ThousandIsland.Socket.send/2 call completes.
• [:socket, :sendfile]: Emitted whenever a ThousandIsland.Socket.sendfile/4 call completes.
• [:socket, :shutdown]: Emitted whenever a ThousandIsland.Socket.shutdown/2 call completes.
• [:socket, :close]: Emitted whenever a ThousandIsland.Socket.close/1 call completes.

Where meaurements indicate a time duration they are are expressed in System :native units for performance reasons. They can be conveted to any desired time unit via System.convert_time_unit/3.