erps v0.5.3 Erps.Daemon View Source

A Process which sits on a TCP port and listens to inbound connections, handing them off to Erps.Server modules when an connection arrives.

The Daemon also manages putting those server processes into supervision trees, usually a DynamicSupervisor. Each server will be seeded with a common initial data and common options, though they may incur specialization once handed off to the Erps.Server module's start_link/2 and init/1 functions.

Example:

this invocation will initialize the Erps.Server MyServer with an empty map, supervised by the DynamicSupervisor named ServerSupervisor. See start_link/2 for more supervision options.

Erps.Daemon.start_link(MyServer, %{}, port: <port_number>, server_supervisor: ServerSupervisor)

Typically, you will also want to supervise Erps.Daemon itself, in which case you should use the following form, passing it into a static Supervisor:

children = [{Erps.Daemon, {MyServer, %{}, port: <port_number>, server_supervisor: ServerSupervisor}}]

You may override the standard child_spec parameters [:id, :restart, :shutdown] in the options list of the tuple.

Link to this section Summary

Functions

Invoked to handle synchronous call/3 messages. call/3 will block until a reply is received (unless the call times out or nodes are disconnected).

Invoked to handle all other messages.

retrieve the TCP port that the erps daemon is bound to.

launches a Erps Daemon, linked to the calling process

Link to this section Types

Link to this section Functions

Link to this function

handle_call(atom, from, state) View Source

Invoked to handle synchronous call/3 messages. call/3 will block until a reply is received (unless the call times out or nodes are disconnected).

request is the request message sent by a call/3, from is a 2-tuple containing the caller's PID and a term that uniquely identifies the call, and state is the current state of the GenServer.

Returning {:reply, reply, new_state} sends the response reply to the caller and continues the loop with new state new_state.

Returning {:reply, reply, new_state, timeout} is similar to {:reply, reply, new_state} except that it also sets a timeout. See the "Timeouts" section in the module documentation for more information.

Returning {:reply, reply, new_state, :hibernate} is similar to {:reply, reply, new_state} except the process is hibernated and will continue the loop once a message is in its message queue. If a message is already in the message queue this will be immediately. Hibernating a GenServer causes garbage collection and leaves a continuous heap that minimises the memory used by the process.

Returning {:reply, reply, new_state, {:continue, continue}} is similar to {:reply, reply, new_state} except c:handle_continue/2 will be invoked immediately after with the value continue as first argument.

Hibernating should not be used aggressively as too much time could be spent garbage collecting. Normally it should only be used when a message is not expected soon and minimising the memory of the process is shown to be beneficial.

Returning {:noreply, new_state} does not send a response to the caller and continues the loop with new state new_state. The response must be sent with reply/2.

There are three main use cases for not replying using the return value:

  • To reply before returning from the callback because the response is known before calling a slow function.
  • To reply after returning from the callback because the response is not yet available.
  • To reply from another process, such as a task.

When replying from another process the GenServer should exit if the other process exits without replying as the caller will be blocking awaiting a reply.

Returning {:noreply, new_state, timeout | :hibernate | {:continue, continue}} is similar to {:noreply, new_state} except a timeout, hibernation or continue occurs as with a :reply tuple.

Returning {:stop, reason, reply, new_state} stops the loop and c:terminate/2 is called with reason reason and state new_state. Then the reply is sent as the response to call and the process exits with reason reason.

Returning {:stop, reason, new_state} is similar to {:stop, reason, reply, new_state} except a reply is not sent.

This callback is optional. If one is not implemented, the server will fail if a call is performed against it.

Callback implementation for GenServer.handle_call/3.

Link to this function

handle_info(atom, state) View Source

Invoked to handle all other messages.

msg is the message and state is the current state of the GenServer. When a timeout occurs the message is :timeout.

Return values are the same as c:handle_cast/2.

This callback is optional. If one is not implemented, the received message will be logged.

Callback implementation for GenServer.handle_info/2.

retrieve the TCP port that the erps daemon is bound to.

Useful for tests - when we want to assign it a port of 0 so that it gets "any free port" of the system.

Link to this function

start(server_module, data, options \\ []) View Source

see start_link/2

Link to this function

start_link(server_module, data, options! \\ []) View Source

launches a Erps Daemon, linked to the calling process

You can pass these general options which will propagate to the Erps.Servers. You may also want to specify the supervision tree using the :server_supervisor option as follows:

  • server_supervisor: pid_or_name assumes the supervisor is DynamicSupervisor (or equivalent) and calls DynamicSupervisor.start_child/2
  • server_supervisor: {module, name} allows you to use a generic module for supervision and calls module.start_child/2 with the server module and the arity-2 parameters for the server_module.start_link/2 function.
  • forward_callers: true causes the daemon and its spawned servers to adopt the universe of the caller. see Multiverses for details

other options you may want to override:

  • :port, sets the TCP port the daemon will listen on. Defaults to 0, which means that a random port will be selected, and must be retrieved using port/1
  • :transport, useful for mocking with TCP instead of TLS in tests
  • :tls_opts, useful for specifiying TLS parameters shared by all server processes