docs are unclear about GenServer handle_* calls cancelling read timeouts

[Dowwie]

From the Handler documentation, ThousandIsland.Handler behaviour, step 4:

any GenServer handle_* calls which are processed directly by an > implementing module will cancel any async read timeout values which may have been set.

It's hard to understand from the documentation what this is referring to.

[mtrudel]

Noted and agreed! I'll get this updated just as soon as I can!

[Dowwie]

@mtrudel for my own understanding, any anyone who searches this in the future, and before official docs explain more clearly-- what is this about? :)

[mtrudel]

This is describing the fact that, if your Handler implementation happens to implement any other handle_* calls other than those that are part of the ThousandIsland.Handler behaviour, any read timeout is cancelled. For example, if you have a handler like this:

defmodule Echo do
  @moduledoc """
  A sample Handler implementation of the Echo protocol
  https://en.wikipedia.org/wiki/Echo_Protocol
  """

  use ThousandIsland.Handler

  @impl ThousandIsland.Handler
  def handle_data(data, socket, state) do
    ThousandIsland.Socket.send(socket, data)
    {:continue, state, 60_000}
  end

  def handle_info(msg, state), do:
    # Calling this will cancel the 60s timeout set above
    {:noreply, state}
  end
end

The reason for this is that Thousand Island itself is just a bit of sugar on top of GenServer, and read timeouts are set as part of this sugar. (This is the same reason that any such handle_info/2 calls will see state as {socket, state}). If you do implement callbacks as above, you can always pass any GenServer compliant result tuple back, including those that seem timeouts.