defmodule LocationSimulator.Event do
  @moduledoc """
  Callback api is a brigde for worker call your code.

  Has three callback apis: start/2, event/2, stop/2

  All these have 2 parameters is config & state.

  config includes lib's config and your meta data you need pass to module.

  state is data that is generated by worker. state is an Elixir map with key:

  :start_time - Unix timestamp the worker start.

  :success - Number of event success.

  :failed - Number of event failed.

  :error - Number of event error

  :gps - GPS data of current state.

  :stop_time - Timestamp worker done, only in stop callback api.

  GPS data is map with key:

  :timestamp - delta time in milisecond from start event (stored in state with key :start_time).

  :lon - Longitude

  :lat - Latitude

  :ele - elevation (meter)

  ## Example

  Please go to example folder in [repo](https://github.com/ohhi-vn/location_simulator)
  """

  @doc """
  start event will be trigger when worker start.

  In this event gps & :end_time won't exist.

  result return to worker for success is {:ok, new_config}. new_config will be used for next event.

  if return {:error, reason} the worker will stop working.
  """
  @callback start(config :: map, state :: map) :: {:ok, map} | {:error, reason :: any}

  @doc """
  event callback will be trigger every worker generated a new GPS data. Time between event is calculated by interval + random(random_range).

  If result is {:stop, reason} the worker will stop working.
  """
  @callback event(config :: map, state :: map) :: {:ok, map} | {:error, reason :: any} | {:stop, reason :: any}

  @doc """
  stop will be trigger when worker send all gps event. In this event you have all information for calculating time, distance, speed.
  """
  @callback stop(config :: map, state :: map) :: {:ok, map} | {:error, reason :: any}
end