LocationSimulator.Event behaviour (LocationSimulator v0.9.0)

Copy Markdown View Source

Callback behaviour that bridges the worker and your application code.

Implement all three callbacks in a module and pass it as :callback in the simulator config.

Callback lifecycle

start/2 → event/2 → event/2 → … → stop/2

state map keys

KeyTypeAvailable in
:start_timenon_neg_integer() (unix s)all callbacks
:successnon_neg_integer()event/2, stop/2
:failednon_neg_integer()event/2, stop/2
:errornon_neg_integer()event/2, stop/2
:gpsgps_point/0event/2, stop/2
:stop_timenon_neg_integer() (unix s)stop/2 only

GPS point map (:gps key)

KeyTypeDescription
:latfloat()Latitude in decimal degrees
:lonfloat()Longitude in decimal degrees
:elefloat()Elevation in metres
:timestampinteger()Milliseconds elapsed since worker start

| :time | NaiveDateTime.t() | nil | Original GPX timestamp (GPX workers only) |

Minimal example

defmodule MyApp.GpsHandler do
  @behaviour LocationSimulator.Event

  @impl true
  def start(config, _state), do: {:ok, config}

  @impl true
  def event(config, %{gps: gps} = _state) do
    MyApp.Tracker.push(gps.lat, gps.lon)
    {:ok, config}
  end

  @impl true
  def stop(config, state) do
    MyApp.Tracker.finish(state.success, state.failed)
    {:ok, config}
  end
end

Summary

Types

gps_point()

GPS point map delivered to event/2 and stop/2 via state.gps.

Callbacks

event(config, state)

Called for each generated GPS point.

start(config, state)

Called once when the worker starts, before any GPS events.

stop(config, state)

Called once after the last GPS event (or when a stop is requested).

Types

gps_point()

@type gps_point() :: %{
  :lat => float(),
  :lon => float(),
  :ele => float(),
  :timestamp => non_neg_integer(),
  optional(:time) => NaiveDateTime.t() | nil
}

GPS point map delivered to event/2 and stop/2 via state.gps.

Callbacks

event(config, state)

@callback event(config :: map(), state :: map()) ::
  {:ok, config :: map()} | {:error, reason :: any()} | {:stop, reason :: any()}

Called for each generated GPS point.

  • {:ok, config} – success; worker continues with the returned config.
  • {:error, reason} – increments :failed counter; worker continues.
  • {:stop, reason} – worker stops gracefully after firing stop/2.

start(config, state)

@callback start(config :: map(), state :: map()) ::
  {:ok, config :: map()} | {:error, reason :: any()}

Called once when the worker starts, before any GPS events.

Return {:ok, config} with an optionally updated config map. Return {:error, reason} to abort the worker before it generates any data.

stop(config, state)

@callback stop(config :: map(), state :: map()) ::
  {:ok, config :: map()} | {:error, reason :: any()}

Called once after the last GPS event (or when a stop is requested).

:stop_time is available in state here.