Ratatouille

v0.5.1

Ratatouille v0.5.1 Ratatouille.Runtime View Source

A runtime for apps implementing the Ratatouille.App behaviour. See Ratatouille.App for details on how to build apps.

Runtime Context

The runtime provides a map with additional context to the app's Ratatouille.App.init/1 callback. This can be used, for example, to get information about the terminal window. Currently, the following attributes are provided via the map:

  • :window: A map with :height and :width keys.

Shutdown Options

When a quit event is received (by default, "q", "Q" or ctrl-c), the runtime will carry out the configured shutdown strategy. The default strategy (:self) just stops the runtime process itself. In certain cases, it may be desirable to stop an OTP application or the system itself, so a few other strategies are provided:

  • :supervisor - Stops the runtime supervisor, which will terminate the runtime process and other dependencies. The VM will still be running afterwards unless stopped by other means.
  • {:application, name} - Stops the named application. The VM will still be running afterwards unless stopped by other means.
  • :system: Gracefully stops the system (calls :init.stop/0). Gracefully shutting down the VM ensures that all applications are stopped. There will be some lag between sending the quit event and the OS process actually exiting, as the VM needs about a second to stop this way. See the note below if this is a problem.

If the :system option is too slow, it's possible to halt the system manually with System.halt/0. It's just important to ensure that the system is only halted after the terminal was restored to its original state. Otherwise, there may be rendering artifacts or issues with the cursor. The :supervisor option can be used to properly halt the system by monitoring the runtime supervisor and halting once it has exited. Alternatively, use the :application option to stop an application that runs the runtime supervisor and halt in the application's stop/1 callback.

Link to this section Summary

Functions

child_spec(arg)

Returns a specification to start this module under a supervisor.

run(state)
start_link(config)

Starts the application runtime given a module defining a Ratatouille terminal application.

Link to this section Functions

Link to this function

child_spec(arg)

View Source

Returns a specification to start this module under a supervisor.

arg is passed as the argument to Task.start_link/1 in the :start field of the spec.

For more information, see the Supervisor module, the Supervisor.child_spec/2 function and the Supervisor.child_spec/0 type.

Link to this function

run(state)

View Source 
run(Ratatouille.Runtime.State.t()) :: :ok
Link to this function

start_link(config)

View Source 
start_link(Keyword.t()) :: {:ok, pid()}

Starts the application runtime given a module defining a Ratatouille terminal application.

Configuration

  • :app (required) - The Ratatouille.App to run.
  • :shutdown - The strategy for stopping the terminal application when a quit event is received.
  • :interval - The runtime loop interval in milliseconds. The default interval is 500 ms. A subscription can be fulfilled at most once every interval, so this effectively configures the maximum subscription resolution that's possible.
  • :quit_events - Specifies the events that should quit the terminal application. Given as a list of tuples conforming where each tuple conforms to either {:ch, ch} or {:key, key}. If not specified, ctrl-c and q / Q can be used to quit the application by default.