Abyss (Abyss v0.2.0)

View Source

Abyss is a modern, pure Elixir UDP socket server

Summary

Types

A module implementing Abyss.Transport behaviour

A keyword list of options to be passed to the transport module's listen/2 function

Functions

Resume a suspended server. This will reopen the listening port, and resume the acceptance of new connections

Starts a Abyss instance with the given options. Returns a pid that can be used to further manipulate the server via other functions defined on this module in the case of success, or an error tuple describing the reason the server was unable to start in the case of failure.

Synchronously stops the given server, waiting up to the given number of milliseconds for existing connections to finish up. Immediately upon calling this function, the server stops listening for new connections, and then proceeds to wait until either all existing connections have completed or the specified timeout has elapsed.

Suspend the server. This will close the listening port, and will stop the acceptance of new connections. Existing connections will stay connected and will continue to be processed.

Types

options()

@type options() :: [
  handler_module: module(),
  handler_options: term(),
  genserver_options: GenServer.options(),
  supervisor_options: [Supervisor.option()],
  port: :inet.port_number(),
  transport_module: module(),
  transport_options: transport_options(),
  num_acceptors: pos_integer(),
  num_connections: non_neg_integer() | :infinity,
  max_connections_retry_count: non_neg_integer(),
  max_connections_retry_wait: timeout(),
  read_timeout: timeout(),
  shutdown_timeout: timeout(),
  silent_terminate_on_error: boolean()
]

transport_module()

@type transport_module() :: Abyss.Transport.UDP

A module implementing Abyss.Transport behaviour

transport_options()

@type transport_options() :: Abyss.Transport.listen_options()

A keyword list of options to be passed to the transport module's listen/2 function

Functions

resume(supervisor)

Resume a suspended server. This will reopen the listening port, and resume the acceptance of new connections

start_link(opts \\ [])

@spec start_link(options()) :: Supervisor.on_start()

Starts a Abyss instance with the given options. Returns a pid that can be used to further manipulate the server via other functions defined on this module in the case of success, or an error tuple describing the reason the server was unable to start in the case of failure.

stop(supervisor, connection_wait \\ 15000)

@spec stop(Supervisor.supervisor(), timeout()) :: :ok

Synchronously stops the given server, waiting up to the given number of milliseconds for existing connections to finish up. Immediately upon calling this function, the server stops listening for new connections, and then proceeds to wait until either all existing connections have completed or the specified timeout has elapsed.

suspend(supervisor)

Suspend the server. This will close the listening port, and will stop the acceptance of new connections. Existing connections will stay connected and will continue to be processed.

The server can later be resumed by calling resume/1, or shut down via standard supervision patterns.

If this function returns :error, it is unlikely that the server is in a useable state

Note that if you do not explicitly set a port (or if you set port to 0), then the server will bind to a different port when you resume it. This new port can be obtained as usual via the listener_info/1 function. This is not a concern if you explicitly set a port value when first instantiating the server