GenStateMachine

https://hexdocs.pm/gen_state_machine/
Admin
GenStateMachine is an idiomatic Elixir wrapper for gen_statem in OTP that simplifies implementing...
Tokens:14,202
Snippets:150
Trust Score:9
Update:6 months ago
Show doc for...
Tokens:
Raw
### POST /start

Source: https://hexdocs.pm/gen_state_machine/index.html

Starts a GenStateMachine process.

```APIDOC
## POST /start

### Description
Starts a `GenStateMachine` process without links (outside of a supervision tree).

### Method
POST

### Endpoint
/start

### Parameters
#### Request Body
- **module** (atom) - Required - The module implementing the state machine.
- **args** (term) - Required - Arguments passed to the init callback.
- **options** (list) - Optional - Options for starting the process.
```

--------------------------------

### Next state usage example

Source: https://hexdocs.pm/gen_state_machine_helpers/index.html

Example usage of next_state/2 in an IEx session.

```elixir
iex> GenStateMachineHelpers.next_state(%{}, :idle)
{:next_state, :idle, %{}}
```

--------------------------------

### Start GenStateMachine With Link

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Use `start_link/3` to start a GenStateMachine process and link it to the current process. This is commonly used within a supervision tree, allowing the supervisor to monitor and restart the GenStateMachine if it fails. The `options` parameter defaults to an empty list.

```elixir
start_link(module, args, options \
  [])
```

--------------------------------

### Next state with reply usage example

Source: https://hexdocs.pm/gen_state_machine_helpers/index.html

Example usage of next_state/3 in an IEx session.

```elixir
iex> GenStateMachineHelpers.next_state(%{}, :idle, [{:reply, :from, :result}])
{:next_state, :idle, %{}, [{:reply, :from, :result}]}
```

--------------------------------

### Start GenStateMachine Without Links

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Use `start/3` to start a GenStateMachine process independently, without establishing links to the current process. This is suitable for processes that do not need to be supervised directly by the caller. The `options` parameter defaults to an empty list.

```elixir
start(module, args, options \
  [])
```

--------------------------------

### Keep state usage example

Source: https://hexdocs.pm/gen_state_machine_helpers/index.html

Example usage of keep_state/1 in an IEx session.

```elixir
iex> GenStateMachineHelpers.keep_state(%{})
{:keep_state, %{}}
```

--------------------------------

### Registering a GenStateMachine locally

Source: https://hexdocs.pm/gen_state_machine/index.html

Demonstrates starting a server and registering it with an atom name for direct communication.

```elixir
# Start the server and register it locally with name MySwitch
{:ok, _} = GenStateMachine.start_link(Switch, {:off, 0}, name: MySwitch)

# Now messages can be sent directly to MySwitch
GenStateMachine.call(MySwitch, :get_count) #=> 0
```

--------------------------------

### Keep state with reply usage example

Source: https://hexdocs.pm/gen_state_machine_helpers/index.html

Example usage of keep_state/2 in an IEx session.

```elixir
iex> GenStateMachineHelpers.keep_state(%{}, [{:reply, :from, :result}])
{:keep_state, %{}, [{:reply, :from, :result}]}
```

--------------------------------

### start_link/3

Source: https://hexdocs.pm/gen_state_machine/index.html

Starts a GenStateMachine process linked to the current process.

```APIDOC
## start_link(module, args, options)

### Description
Starts a GenStateMachine process linked to the current process, typically used in a supervision tree.

### Parameters
- **module** (module()) - Required - The module implementing the state machine.
- **args** (any()) - Required - Arguments passed to init/1.
- **options** (GenServer.options()) - Optional - Configuration options like :name, :timeout, :debug, or :spawn_opt.
```

--------------------------------

### Handle Event and Reply in One Second

Source: https://hexdocs.pm/gen_state_machine/index.html

Example demonstrating how to schedule a reply using `Process.send_after` within a `handle_event` callback. The state remains the same, and data is kept.

```elixir
def handle_event({:call, from}, :reply_in_one_second, state, data) do
  Process.send_after(self(), {:reply, from}, 1_000)
  :keep_state_and_data
end

def handle_event(:info, {:reply, from}, state, data) do
  GenStateMachine.reply(from, :one_second_has_passed)
end
```

--------------------------------

### init/1

Source: https://hexdocs.pm/gen_state_machine/index.html

Initializes the GenStateMachine with the provided arguments. This is the first callback invoked when the GenStateMachine starts.

```APIDOC
## init/1

### Description
Initializes the `GenStateMachine` with the provided arguments. This is the first callback invoked when the `GenStateMachine` starts.

### Method
N/A (Callback function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
Typically returns `{:ok, state, data}` or `{:stop, reason}`.

#### Response Example
None
```

--------------------------------

### Start GenStateMachine Process (Linked)

Source: https://hexdocs.pm/gen_state_machine/index.html

Starts a `GenStateMachine` process and links it to the current process, typically for use within a supervision tree. The function returns `{:ok, pid}` upon successful initialization.

```erlang
start_link(module(), any(), GenServer.options()) :: on_start()
```

--------------------------------

### Start GenStateMachine Process (Unlinked)

Source: https://hexdocs.pm/gen_state_machine/index.html

Starts a `GenStateMachine` process without linking it to the current process. Use `start/3` when the state machine does not need to be part of a supervision tree.

```erlang
start(module(), any(), GenServer.options()) :: on_start()
```

--------------------------------

### GenStateMachine init/1 Callback

Source: https://hexdocs.pm/gen_state_machine/index.html

Called when the GenStateMachine server starts. It initializes the state and data. The return value determines the initial behavior of the GenStateMachine.

```Elixir
init(args :: term()) :: :gen_statem.init_result(state())
```

--------------------------------

### init/1 Callback

Source: https://hexdocs.pm/gen_state_machine/index.html

Invoked when the GenStateMachine server is started to initialize the state and data.

```APIDOC
## init(args)

### Description
Invoked when the server is started. The function blocks until it returns. It initializes the state machine with the provided arguments.

### Parameters
- **args** (term) - Required - The argument term passed to start_link/3.

### Response
- **{:ok, state, data}** - Successful initialization.
- **{:ok, state, data, actions}** - Successful initialization with execution of actions.
- **:ignore** - Process exits normally without entering the loop.
- **{:stop, reason}** - Process exits with the specified reason.
```

--------------------------------

### Install GenStateMachineHelpers dependency

Source: https://hexdocs.pm/gen_state_machine_helpers/readme.html

Add the package to the dependencies list in your mix.exs file.

```elixir
def deps do
  [
    {:gen_state_machine_helpers, "~> 0.1.0"}
  ]
end
```

--------------------------------

### Initialize GenStateMachine

Source: https://hexdocs.pm/gen_state_machine/index.html

The initialization callback for a GenStateMachine. It is invoked when the GenStateMachine is started and receives the arguments passed during the start process.

```erlang
init(args)
```

--------------------------------

### GenStateMachine On Start Return Type

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Specifies the return type when a GenStateMachine server is successfully started. Refer to the Erlang documentation for a complete definition.

```elixir
on_start() :: :gen_statem.start_ret()
```

--------------------------------

### Handle event with keep_state

Source: https://hexdocs.pm/gen_state_machine_helpers/index.html

Example of using keep_state within a pipeline inside a handle_event function.

```elixir
def handle_event(:cast, {:add, num}, data) do
  data
  |> update_in([:num], & &1 + num)
  |> keep_state
end
```

--------------------------------

### Implement GenStateMachine with helpers

Source: https://hexdocs.pm/gen_state_machine_helpers/readme.html

Import GenStateMachineHelpers to use pipeline-friendly state transition functions within a state machine module.

```elixir
defmodule StatemLib.Phone do
  use GenStateMachine, callback_mode: :state_functions

  # import this package
  import GenStateMachineHelpers

  require Logger

  def start_link do
    GenStateMachine.start_link __MODULE__, {:initialize, %{}}
  end

  def setup(pid, extension, id) do
    GenStateMachine.cast pid, {:setup, extension, id}
  end

  def call(pid, extension) do
    GenStateMachine.call pid, {:call, extension}
  end

  def hangup(pid) do
    GenStateMachine.call pid, :hangup
  end

  def get_status(pid) do
    GenStateMachine.call pid, :get_status
  end

  def initialize(:cast, {:setup, extension, id}, data) do
    data
    |> Map.put(:id, id)
    |> Map.put(:extension, extension)
    |> next_state(:idle)
  end

  def initialize(event_type, event_content, data) do
    handle_event(event_type, event_content, data)
  end

  def idle({:call, from}, {:call, extension}, data) do
    data
    |> Map.put(:dest_extension, extension)
    |> next_state(:calling, [{:reply, from, {:calling, extension}}])
  end

  def idle(event_type, event_content, data) do
    handle_event(event_type, event_content, data)
  end

  def calling(event_type, event_content, data) do
    handle_event(event_type, event_content, data)
  end

  def handle_event({:call, from}, :get_status, data) do
    keep_state, date, [{:reply, from, data}]
  end

  def handle_event({:call, from}, :hangup, data) do
    data
    |> Map.delete(:dest_extension)
    |> next_state(:idle, [{:reply, from, :idle}])
  end

  def handle_event(a, b, data) do
    keep_state data
  end
end
```

--------------------------------

### Add application to mix.exs

Source: https://hexdocs.pm/gen_state_machine/readme.html

Ensure the library is included in the application list.

```elixir
  def application do
    [applications: [:gen_state_machine]]
  end
```

--------------------------------

### GenStateMachine Client/Server API

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Guidelines for implementing public API functions and server callbacks within a GenStateMachine module.

```APIDOC
## Client/Server API Implementation

### Description
It is recommended to wrap `GenStateMachine` calls in public functions to define a clear API for the server. Server logic is implemented via `handle_event/4` callbacks.

### Implementation Pattern
- **Client**: Functions that call `GenStateMachine.cast/2` or `GenStateMachine.call/3`.
- **Server**: `handle_event/4` callbacks that pattern match on event types and states to return `{:next_state, ...}`.

### Example
```elixir
defmodule Switch do
  use GenStateMachine

  def flip(pid), do: GenStateMachine.cast(pid, :flip)

  def handle_event(:cast, :flip, :off, data), do: {:next_state, :on, data + 1}
end
```
```

--------------------------------

### Implement state entry callbacks

Source: https://hexdocs.pm/gen_state_machine/index.html

Enables state entry notifications by adding :state_enter to the callback_mode, allowing logic to execute upon entering a state.

```elixir
defmodule Switch do
  use GenStateMachine, callback_mode: [:handle_event_function, :state_enter]

  def handle_event(:enter, _event, state, data) do
    {:next_state, state, %{data | enters: data.enters + 1}}
  end

  def handle_event(:cast, :flip, :off, data) do
    {:next_state, :on, %{data | flips: data.flips + 1}}
  end

  def handle_event(:cast, :flip, :on, data) do
    {:next_state, :off, data}
  end

  def handle_event({:call, from}, :get_count, _state, data) do
    {:keep_state_and_data, [{:reply, from, data}]}
  end
end

# Start the server
{:ok, pid} = GenStateMachine.start_link(Switch, {:off, %{enters: 0, flips: 0}})

# This is the client
GenStateMachine.cast(pid, :flip)
GenStateMachine.cast(pid, :flip)
#=> :ok

GenStateMachine.call(pid, :get_count)
#=> %{enters: 3, flips: 1}
```

--------------------------------

### Implementing a GenStateMachine module

Source: https://hexdocs.pm/gen_state_machine/index.html

Shows the recommended pattern of wrapping GenStateMachine calls in public API functions within the same module.

```elixir
defmodule Switch do
  use GenStateMachine

  # Client

  def start_link() do
    GenStateMachine.start_link(Switch, {:off, 0})
  end

  def flip(pid) do
    GenStateMachine.cast(pid, :flip)
  end

  def get_count(pid) do
    GenStateMachine.call(pid, :get_count)
  end

  # Server (callbacks)

  def handle_event(:cast, :flip, :off, data) do
    {:next_state, :on, data + 1}
  end

  def handle_event(:cast, :flip, :on, data) do
    {:next_state, :off, data}
  end

  def handle_event({:call, from}, :get_count, state, data) do
    {:next_state, state, data, [{:reply, from, data}]}
  end

  def handle_event(event_type, event_content, state, data) do
    # Call the default implementation from GenStateMachine
    super(event_type, event_content, state, data)
  end
end
```

--------------------------------

### next_state/3

Source: https://hexdocs.pm/gen_state_machine_helpers/GenStateMachineHelpers.html

Returns the {:next_state, state_name, data, reply} tuple. This function transitions to a new state and provides a reply.

```APIDOC
## next_state/3

### Description
Returns the {:next_state, state_name, data, reply} tuple.

### Function Signature
```elixir
next_state(data, state_name, reply) :: {:next_state, atom, any, any}
```

### Parameters
- **data** (any) - The data associated with the next state.
- **state_name** (atom) - The name of the next state.
- **reply** (any) - The reply tuple to be returned.

### Request Example
```elixir
GenStateMachineHelpers.next_state(%{}, :idle, [{:reply, :from, :result}])
```

### Response Example
```elixir
{:next_state, :idle, %{}, [{:reply, :from, :result}]}
```
```

--------------------------------

### Add dependency to mix.exs

Source: https://hexdocs.pm/gen_state_machine/readme.html

Include the library in the project dependencies.

```elixir
  def deps do
    [{:gen_state_machine, "~> 2.0"}]
  end
```

--------------------------------

### POST /call

Source: https://hexdocs.pm/gen_state_machine/index.html

Makes a synchronous call to the server and waits for its reply.

```APIDOC
## POST /call

### Description
Makes a synchronous call to the `server` and waits for its reply.

### Method
POST

### Endpoint
/call

### Parameters
#### Request Body
- **server** (server_ref) - Required - The reference to the GenStateMachine process.
- **request** (term) - Required - The request to send.
- **timeout** (integer | :infinity) - Optional - The timeout duration in milliseconds.
```

--------------------------------

### GenStateMachineHelpers Module

Source: https://hexdocs.pm/gen_state_machine_helpers/api-reference.html

Overview of the GenStateMachineHelpers module and its purpose in the gen_state_machine_helpers library.

```APIDOC
## Module: GenStateMachineHelpers

### Description
This module provides a collection of helper functions designed to assist developers when working with GenStateMachine. It simplifies common tasks and state management operations.

### Usage
Include this module in your GenStateMachine implementation to access the provided utility functions.
```

--------------------------------

### Implement a state machine with state_functions

Source: https://hexdocs.pm/gen_state_machine/index.html

Uses the :state_functions callback mode where messages are handled by functions named after the current state.

```elixir
defmodule Switch do
  use GenStateMachine, callback_mode: :state_functions

  def off(:cast, :flip, data) do
    {:next_state, :on, data + 1}
  end
  def off({:call, from}, :get_count, data) do
    {:keep_state_and_data, [{:reply, from, data}]}
  end

  def on(:cast, :flip, data) do
    {:next_state, :off, data}
  end
  def on({:call, from}, :get_count, data) do
    {:keep_state_and_data, [{:reply, from, data}]}
  end
end

# Start the server
{:ok, pid} = GenStateMachine.start_link(Switch, {:off, 0})

# This is the client
GenStateMachine.cast(pid, :flip)
#=> :ok

GenStateMachine.call(pid, :get_count)
#=> 1
```

--------------------------------

### GenStateMachine Process Registration

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Details on how to register a GenStateMachine process locally, globally, or via custom registries during startup.

```APIDOC
## Process Registration

### Description
GenStateMachine supports registering processes under a name on start using the `:name` option. This allows for easier communication with the process.

### Supported Registration Types
- **atom** - Registered locally via `Process.register/2`.
- **{:global, term}** - Registered globally across nodes.
- **{:via, module, term}** - Registered via a custom registry module (e.g., `:global`).

### Usage Example
```elixir
# Start and register locally
{:ok, _} = GenStateMachine.start_link(Switch, {:off, 0}, name: MySwitch)

# Send message to registered name
GenStateMachine.call(MySwitch, :get_count)
```
```

--------------------------------

### Implement a state machine with handle_event_function

Source: https://hexdocs.pm/gen_state_machine/index.html

Uses the default :handle_event_function callback mode to manage state transitions and handle synchronous calls and asynchronous casts.

```elixir
defmodule Switch do
  use GenStateMachine

  # Callbacks

  def handle_event(:cast, :flip, :off, data) do
    {:next_state, :on, data + 1}
  end

  def handle_event(:cast, :flip, :on, data) do
    {:next_state, :off, data}
  end

  def handle_event({:call, from}, :get_count, state, data) do
    {:next_state, state, data, [{:reply, from, data}]}
  end
end

# Start the server
{:ok, pid} = GenStateMachine.start_link(Switch, {:off, 0})

# This is the client
GenStateMachine.cast(pid, :flip)
#=> :ok

GenStateMachine.call(pid, :get_count)
#=> 1
```

--------------------------------

### next_state/2

Source: https://hexdocs.pm/gen_state_machine_helpers/GenStateMachineHelpers.html

Returns the {:next_state, state_name, data} tuple. This function transitions to a new state with the given data.

```APIDOC
## next_state/2

### Description
Returns the {:next_state, state_name, data} tuple.

### Function Signature
```elixir
next_state(data, state_name) :: {:next_state, atom, any}
```

### Parameters
- **data** (any) - The data associated with the next state.
- **state_name** (atom) - The name of the next state.

### Request Example
```elixir
GenStateMachineHelpers.next_state(%{}, :idle)
```

### Response Example
```elixir
{:next_state, :idle, %{}}
```
```

--------------------------------

### Reply to a Specific Client

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Use `reply/2` to send a reply to a specific client. This is useful when handling individual client requests.

```elixir
reply(client, reply)
```

--------------------------------

### POST /cast

Source: https://hexdocs.pm/gen_state_machine/index.html

Sends an asynchronous request to the server.

```APIDOC
## POST /cast

### Description
Sends an asynchronous request to the `server`.

### Method
POST

### Endpoint
/cast

### Parameters
#### Request Body
- **server** (server_ref) - Required - The reference to the GenStateMachine process.
- **request** (term) - Required - The request to send.
```

--------------------------------

### Reply to Clients

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Use `reply/1` to send replies to multiple clients. This is typically used after receiving a request that requires a response.

```elixir
reply(replies)
```

--------------------------------

### Synchronous Call to GenStateMachine

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Use `call/3` to make a synchronous request to a GenStateMachine and wait for its reply. The `timeout` option defaults to `:infinity`.

```elixir
call(server, request, timeout \
  :infinity)
```

--------------------------------

### call/3

Source: https://hexdocs.pm/gen_state_machine/index.html

Makes a synchronous call to the server and waits for a reply.

```APIDOC
## call(server, request, timeout)

### Description
Makes a synchronous call to the server and waits for its reply. The client sends the given request to the server and waits until a reply arrives or a timeout occurs.

### Parameters
- **server** (server_ref()) - Required - The server to call.
- **request** (term()) - Required - The request to send.
- **timeout** (timeout()) - Optional - Milliseconds to wait or :infinity. Default is :infinity.
```

--------------------------------

### GenStateMachine Action Type

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Defines the possible actions that can be returned from a state function or `init/1`. Actions can include state transitions and options like `postpone`, `hibernate`, and `timeout`. Events added via `:next_event` are prioritized.

```elixir
action() :: :gen_statem.action()
```

--------------------------------

### Synchronous Call to GenStateMachine

Source: https://hexdocs.pm/gen_state_machine/index.html

Use `call/3` for synchronous communication with a GenStateMachine. It sends a request and waits for a reply or timeout. Ensure the server reference is valid.

```erlang
call(server_ref(), term(), timeout()) :: term()
```

--------------------------------

### Terminate GenStateMachine

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

The `terminate/3` callback is invoked just before the GenStateMachine process exits. It should be used to perform any necessary cleanup operations.

```elixir
terminate(reason, state, data)
```

--------------------------------

### GenStateMachine Callbacks

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Callbacks that define the behavior and state transitions of a GenStateMachine.

```APIDOC
## Callbacks

### code_change/4

Invoked to change the state of the `GenStateMachine` when a different version of a module is loaded (hot code swapping) and the state and/or data's term structure should be changed.

### format_status/2

Invoked in some cases to retrieve a formatted version of the `GenStateMachine` status.

### handle_event/4

Whenever a `GenStateMachine` in callback mode `:handle_event_function` (the default) receives a call, cast, or normal process message, this callback will be invoked.

### init/1

Invoked when the server is started. `start_link/3` (or `start/3`) will block until it returns.

### state_name/3

Whenever a `GenStateMachine` in callback mode `:state_functions` receives a call, cast, or normal process message, a state function is called.

### terminate/3

Invoked when the server is about to exit. It should do any cleanup required.
```

--------------------------------

### GenStateMachineHelpers Functions

Source: https://hexdocs.pm/gen_state_machine_helpers/index.html

Helper functions to return state machine tuples for keep_state and next_state transitions.

```APIDOC
## keep_state(data)

### Description
Returns the {:keep_state, data} tuple.

### Parameters
- **data** (any) - Required - The current state data.

### Response
- **Result** (tuple) - {:keep_state, data}

## keep_state(data, reply)

### Description
Returns the {:keep_state, data, reply} tuple.

### Parameters
- **data** (any) - Required - The current state data.
- **reply** (any) - Required - The reply tuple.

### Response
- **Result** (tuple) - {:keep_state, data, reply}

## next_state(data, state_name)

### Description
Returns the {:next_state, state_name, data} tuple.

### Parameters
- **data** (any) - Required - The current state data.
- **state_name** (atom) - Required - The next state name.

### Response
- **Result** (tuple) - {:next_state, state_name, data}

## next_state(data, state_name, reply)

### Description
Returns the {:next_state, state_name, data, reply} tuple.

### Parameters
- **data** (any) - Required - The current state data.
- **state_name** (atom) - Required - The next state name.
- **reply** (any) - Required - The reply tuple.

### Response
- **Result** (tuple) - {:next_state, state_name, data, reply}
```

--------------------------------

### Next State Tuple with Reply

Source: https://hexdocs.pm/gen_state_machine_helpers/GenStateMachineHelpers.html

Use this function to return a next_state tuple along with a reply tuple. It takes the current data, the next state name, and the reply information.

```Elixir
next_state(any, atom, any) :: {:next_state, atom, any, any}
```

```Elixir
iex> GenStateMachineHelpers.next_state(%{}, :idle, [{:reply, :from, :result}])
```

```Elixir
{:next_state, :idle, %{}, [{:reply, :from, :result}]}
```

--------------------------------

### code_change/4

Source: https://hexdocs.pm/gen_state_machine/index.html

Handles hot code swapping by changing the state and data of the GenStateMachine when a new version of the module is loaded. It can either succeed, returning the new state and data, or fail, returning a reason.

```APIDOC
## code_change/4

### Description
Invoked to change the state of the `GenStateMachine` when a different version of a module is loaded (hot code swapping) and the state and/or data's term structure should be changed. `old_vsn` is the previous version of the module (defined by the `@vsn` attribute) when upgrading. When downgrading the previous version is wrapped in a 2-tuple with first element `:down`. `state` is the current state of the `GenStateMachine`, `data` is the current data, and `extra` is any extra data required to change the state. Returning `{:ok, new_state, new_data}` changes the state to `new_state`, the data to `new_data`, and the code change is successful. Returning `reason` fails the code change with reason `reason` and the state and data remains the same. If `code_change/4` raises the code change fails and the loop will continue with its previous state. Therefore this callback does not usually contain side effects. This function can optionally throw a result to return it.

### Method
N/A (Callback function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
`{:ok, new_state, new_data}` if the code change is successful.
`reason` if the code change fails.

#### Response Example
None
```

--------------------------------

### terminate/3 Callback

Source: https://hexdocs.pm/gen_state_machine/index.html

Invoked when the server is about to exit to perform cleanup operations.

```APIDOC
## terminate(reason, state, data)

### Description
Invoked when the server is about to exit. It should perform any necessary cleanup. Note that this is not guaranteed to be called in all exit scenarios.

### Parameters
- **reason** (term) - Required - The exit reason.
- **state** (term) - Required - The current state.
- **data** (term) - Required - The current state data.
```

--------------------------------

### reply/2

Source: https://hexdocs.pm/gen_state_machine/index.html

Explicitly sends a reply to a client.

```APIDOC
## reply(client, reply)

### Description
Replies to a client that called call/3 when the reply cannot be specified in the return value of a state function.

### Parameters
- **client** (gen_statem.from()) - Required - The from element of the event type.
- **reply** (term()) - Required - The arbitrary term to return to the client.
```

--------------------------------

### Explicitly Reply to Clients

Source: https://hexdocs.pm/gen_state_machine/index.html

The `reply/1` function is used to send explicit replies to multiple clients. It always returns `:ok`.

```erlang
reply([:gen_statem.reply_action()] | :gen_statem.reply_action()) :: :ok
```

--------------------------------

### terminate/2 Callback

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Invoked when the GenStateMachine is about to exit, allowing for cleanup operations.

```APIDOC
## terminate/2

### Description
Invoked when the server is about to exit. It should do any cleanup required. `reason` is the exit reason, `state` is the current state, and `data` is the current data of the `GenStateMachine`. The return value is ignored.

### Method
Callback

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
- `any()`: The return value is ignored.

#### Response Example
```elixir
:ok
```

```elixir
# No return value needed, cleanup happens here
```
```

--------------------------------

### code_change/4

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Callback invoked during hot code swapping to update state and data structures.

```APIDOC
## code_change(old_vsn, state, data, extra)

### Description
Invoked to change the state of the GenStateMachine when a different version of a module is loaded.

### Parameters
#### Arguments
- **old_vsn** (term | {:down, term}) - Required - The previous version of the module.
- **state** (state) - Required - The current state.
- **data** (data) - Required - The current data.
- **extra** (term) - Required - Extra data required for the change.
```

--------------------------------

### GenStateMachine terminate/2 Callback

Source: https://hexdocs.pm/gen_state_machine/index.html

Invoked when the GenStateMachine server is about to exit. It is used for performing cleanup tasks. Note that this callback is not guaranteed to be called in all exit scenarios.

```Elixir
terminate(reason :: term(), state(), data()) :: any()
```

--------------------------------

### GenStateMachine Hot Code Swapping Callback

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

The `code_change/4` callback is invoked during hot code swapping. It allows you to update the state and/or data terms when a new version of the module is loaded.

```elixir
code_change(old_vsn, state, data, extra)
```

--------------------------------

### POST /stop

Source: https://hexdocs.pm/gen_state_machine/index.html

Stops the GenStateMachine process.

```APIDOC
## POST /stop

### Description
Stops the server with the given `reason`.

### Method
POST

### Endpoint
/stop

### Parameters
#### Request Body
- **server** (server_ref) - Required - The reference to the GenStateMachine process.
- **reason** (term) - Optional - The reason for stopping.
- **timeout** (integer | :infinity) - Optional - The timeout duration.
```

--------------------------------

### Explicitly Reply to a Specific Client

Source: https://hexdocs.pm/gen_state_machine/index.html

Use `reply/2` to send a specific reply to a client that previously called `call/3`. The `client` must be the `from` element of the event, and `reply` is the term to be returned.

```erlang
reply(:gen_statem.from(), term()) :: :ok
```

--------------------------------

### GenStateMachine Functions

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Core functions for managing GenStateMachine processes.

```APIDOC
## Functions

### call/3

Makes a synchronous call to the `server` and waits for its reply.

### cast/2

Sends an asynchronous request to the `server`.

### reply/1

Sends replies to clients.

### reply/2

Replies to a client.

### start/3

Starts a `GenStateMachine` process without links (outside of a supervision tree).

### start_link/3

Starts a `GenStateMachine` process linked to the current process.

### stop/3

Stops the server with the given `reason`.
```

--------------------------------

### Format GenStateMachine Status

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

The `format_status/2` callback is used in specific scenarios to retrieve a formatted representation of the GenStateMachine's status.

```elixir
format_status(reason, pdict_state_and_data)
```

--------------------------------

### cast/2

Source: https://hexdocs.pm/gen_state_machine/index.html

Sends an asynchronous request to the server.

```APIDOC
## cast(server, request)

### Description
Sends an asynchronous request to the server. This function always returns :ok regardless of whether the destination server exists.

### Parameters
- **server** (server_ref()) - Required - The server to send the request to.
- **request** (term()) - Required - The request to send.
```

--------------------------------

### stop/3

Source: https://hexdocs.pm/gen_state_machine/index.html

Stops the GenStateMachine server with a given reason and timeout. It ensures that the terminate callback is invoked before exiting and handles error reporting according to OTP semantics.

```APIDOC
## stop/3

### Description
Stops the server with the given `reason`. The `terminate/2` callback of the given `server` will be invoked before exiting. This function returns `:ok` if the server terminates with the given reason; if it terminates with another reason, the call exits. This function keeps OTP semantics regarding error reporting. If the reason is any other than `:normal`, `:shutdown` or `{:shutdown, _}`, an error report is logged.

### Method
N/A (Callback function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
`:ok` if the server terminates with the given reason.

#### Response Example
None
```

--------------------------------

### Stop GenStateMachine

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Use `stop/3` to gracefully stop a GenStateMachine process. You can specify a `reason` for stopping, which defaults to `:normal`. The `timeout` option defaults to `:infinity`.

```elixir
stop(server, reason \
  :normal, timeout \
  :infinity)
```

--------------------------------

### handle_event/4

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Callback invoked when the GenStateMachine receives a call, cast, or process message.

```APIDOC
## handle_event(event_type, event_content, state, data)

### Description
Invoked when the GenStateMachine receives an event in :handle_event_function mode.

### Parameters
#### Arguments
- **event_type** (atom) - Required - The type of event (e.g., :enter).
- **event_content** (term) - Required - The content of the event.
- **state** (state) - Required - The current state.
- **data** (data) - Required - The current data.
```

--------------------------------

### state_name/3 Callback

Source: https://hexdocs.pm/gen_state_machine/index.html

Handles events (calls, casts, or messages) when the GenStateMachine is in a specific state.

```APIDOC
## state_name(event_type, event_content, data)

### Description
Called when a GenStateMachine in :state_functions mode receives a call, cast, or process message. The function name corresponds to the current state.

### Parameters
- **event_type** (atom) - Required - The type of event (e.g., :enter).
- **event_content** (term) - Required - The content of the event.
- **data** (term) - Required - The current state data.
```

--------------------------------

### Handle Events in GenStateMachine

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

The `handle_event/4` callback is invoked when the GenStateMachine receives a call, cast, or regular process message. This is the default callback mode (`:handle_event_function`).

```elixir
handle_event(atom, old_state, state, data)
```

--------------------------------

### Next State Tuple

Source: https://hexdocs.pm/gen_state_machine_helpers/GenStateMachineHelpers.html

Use this function to return a next_state tuple. It requires the current data and the name of the next state.

```Elixir
next_state(any, atom) :: {:next_state, atom, any}
```

```Elixir
iex> GenStateMachineHelpers.next_state(%{}, :idle)
```

```Elixir
{:next_state, :idle, %{}}
```

--------------------------------

### keep_state/2

Source: https://hexdocs.pm/gen_state_machine_helpers/GenStateMachineHelpers.html

Returns the {:keep_state, data, reply} tuple. This function allows keeping the current state and providing a reply.

```APIDOC
## keep_state/2

### Description
Returns the {:keep_state, data, reply} tuple.

### Function Signature
```elixir
keep_state(data, reply) :: {:keep_state, any, any}
```

### Parameters
- **data** (any) - The data to be kept in the state.
- **reply** (any) - The reply tuple to be returned.

### Request Example
```elixir
GenStateMachineHelpers.keep_state(%{}, [{:reply, :from, :result}])
```

### Response Example
```elixir
{:keep_state, %{}, [{:reply, :from, :result}]}
```
```

--------------------------------

### Stop GenStateMachine Server

Source: https://hexdocs.pm/gen_state_machine/index.html

Stops the GenStateMachine server with a specified reason and timeout. The terminate/2 callback is invoked before exiting. Returns :ok if the server terminates with the given reason; otherwise, the call exits.

```erlang
stop(server_ref(), reason :: term(), timeout()) :: :ok
```

--------------------------------

### Next state with reply definition

Source: https://hexdocs.pm/gen_state_machine_helpers/index.html

Type specification for the next_state/3 function.

```elixir
next_state(any, atom, any) :: {:next_state, atom, any, any}
```

--------------------------------

### stop/3

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Stops the GenStateMachine process with a specified reason.

```APIDOC
## stop(server_ref, reason, timeout)

### Description
Stops the server with the given reason. The terminate/2 callback is invoked before exiting.

### Parameters
#### Arguments
- **server_ref** (term) - Required - The reference to the server process.
- **reason** (term) - Required - The reason for termination.
- **timeout** (term) - Required - The timeout duration for the stop operation.
```

--------------------------------

### Asynchronous Cast to GenStateMachine

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Use `cast/2` to send an asynchronous request to a GenStateMachine. This function does not wait for a reply.

```elixir
cast(server, request)
```

--------------------------------

### format_status/2

Source: https://hexdocs.pm/gen_state_machine/index.html

Provides a formatted representation of the GenStateMachine's status, useful for controlling the appearance of status information, especially for large state or data terms.

```APIDOC
## format_status/2

### Description
Invoked in some cases to retrieve a formatted version of the `GenStateMachine` status. This callback can be useful to control the _appearance_ of the status of the `GenStateMachine`. For example, it can be used to return a compact representation of the `GenStateMachines`'s state/data to avoid having large terms printed. `pdict_state_and_data` is a three-element list `[pdict, state, data]` where `pdict` is a list of `{key, value}` tuples representing the current process dictionary of the `GenStateMachine`, `state` is the current state of the `GenStateMachine`, and `data` is the current data. This function can optionally throw a result to return it.

### Method
N/A (Callback function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
`term()` - A formatted representation of the GenStateMachine's status.

#### Response Example
None
```

--------------------------------

### State Functions (e.g., state_name/3)

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Handles events (calls, casts, messages) within a specific state. The function name corresponds to the state name.

```APIDOC
## state_name/3

### Description
Whenever a `GenStateMachine` in callback mode `:state_functions` receives a call, cast, or normal process message, a state function is called. This spec documents the callback; the actual function name will be the name of the state.

### Method
Callback

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (state_enter_result or event_handler_result)
- `{:next_state, new_state}`: Transitions to a new state.
- `{:next_state, new_state, new_data}`: Transitions to a new state with updated data.
- `{:next_state, new_state, new_data, actions}`: Transitions to a new state with updated data and executes actions.
- `:stop`: Stops the GenStateMachine process.
- `{:stop, reason}`: Stops the GenStateMachine process with a specific reason.
- `{:stop, reason, new_data}`: Stops the GenStateMachine process with a specific reason and updated data.
- `{:stop, reason, new_data, actions}`: Stops the GenStateMachine process with a specific reason, updated data, and executes actions.

#### Response Example
```elixir
{:next_state, :new_state_name}
```

```elixir
{:next_state, :new_state_name, %{new_field: "value"}}
```

```elixir
{:next_state, :new_state_name, %{new_field: "value"}, [:action1, :action2]}
```

```elixir
:stop
```

```elixir
{:stop, :normal}
```

```elixir
{:stop, :normal, %{updated_data: true}}
```

```elixir
{:stop, :normal, %{updated_data: true}, [:cleanup_action]}
```
```

--------------------------------

### Handle Code Change in GenStateMachine

Source: https://hexdocs.pm/gen_state_machine/index.html

Invoked during hot code swapping to change the state and data of a GenStateMachine when a new module version is loaded. It accepts the old version, current state, current data, and extra data. Returns {:ok, new_state, new_data} on success or a reason on failure. Does not typically have side effects.

```erlang
code_change(
  old_vsn :: term() | {:down, vsn :: term()},
  state(),
  data(),
  extra :: term()
) :: {:ok, state(), data()} | (reason :: term())
```

--------------------------------

### State Name Callback

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

The `state_name/3` callback is invoked when the GenStateMachine is in `:state_functions` callback mode and receives a call, cast, or normal process message. A state function is then called based on the current state.

```elixir
state_name(atom, old_state_name, data)
```

--------------------------------

### GenStateMachine state_name/3 Callback

Source: https://hexdocs.pm/gen_state_machine/index.html

Handles events within a specific state. This function is called when a GenStateMachine receives a call, cast, or normal process message.

```Elixir
state_name(:enter, old_state_name :: state_name(), data()) ::
  state_enter_result(state_name())
```

```Elixir
state_name(event_type(), event_content(), data()) ::
  event_handler_result(state_name())
```

--------------------------------

### Asynchronous Cast to GenStateMachine

Source: https://hexdocs.pm/gen_state_machine/index.html

Use `cast/2` to send an asynchronous message to a GenStateMachine. This function always returns `:ok` and does not confirm message delivery or handling.

```erlang
cast(server_ref(), term()) :: :ok
```

--------------------------------

### Stop GenStateMachine Process

Source: https://hexdocs.pm/gen_state_machine/index.html

Stops a `GenStateMachine` process. The `reason` defaults to `:normal` and `timeout` defaults to `:infinity`. This function is used to gracefully terminate a state machine.

```erlang
stop(server, reason \\ :normal, timeout \\ :infinity) :: term()
```

--------------------------------

### Next state function definition

Source: https://hexdocs.pm/gen_state_machine_helpers/index.html

Type specification for the next_state/2 function.

```elixir
next_state(any, atom) :: {:next_state, atom, any}
```

--------------------------------

### Keep State Tuple with Reply

Source: https://hexdocs.pm/gen_state_machine_helpers/GenStateMachineHelpers.html

Use this function to return a keep_state tuple along with a reply tuple. It accepts the current data and the reply information.

```Elixir
keep_state(any, any) :: {:keep_state, any, any}
```

```Elixir
iex> GenStateMachineHelpers.keep_state(%{}, [{:reply, :from, :result}])
```

```Elixir
{:keep_state, %{}, [{:reply, :from, :result}]}
```

--------------------------------

### GenStateMachine Server Reference Type

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Defines the type for references to GenStateMachine servers, which can be atoms or PIDs. Refer to the Erlang documentation for a complete definition.

```elixir
server_ref() :: :gen_statem.server_ref()
```

--------------------------------

### Handle Events in GenStateMachine

Source: https://hexdocs.pm/gen_state_machine/index.html

Invoked when a GenStateMachine in callback mode :handle_event_function receives a call, cast, or normal process message. Handles specific entry events or general event types and content. Can optionally throw a result.

```erlang
handle_event(:enter, old_state :: state(), state(), data()) ::
  state_enter_result(state())
```

```erlang
handle_event(event_type(), event_content(), state(), data()) ::
  event_handler_result(state())
```

--------------------------------

### GenStateMachine Event Type

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Indicates the source of the current event being processed by the GenStateMachine. Possible values include `:call`, `:cast`, `:info`, `:timeout`, `:state_timeout`, and `:internal`.

```elixir
event_type() :: :gen_statem.event_type()
```

--------------------------------

### handle_event/4

Source: https://hexdocs.pm/gen_state_machine/index.html

Handles events received by the GenStateMachine when in callback mode `:handle_event_function`. It processes different event types and their content to update the state.

```APIDOC
## handle_event/4

### Description
Whenever a `GenStateMachine` in callback mode `:handle_event_function` (the default) receives a call, cast, or normal process messsage, this callback will be invoked. This function can optionally throw a result to return it.

### Method
N/A (Callback function)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
`state_enter_result(state())` for `:enter` event type.
`event_handler_result(state())` for other event types.

#### Response Example
None
```

--------------------------------

### GenStateMachine State Type

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Represents the current state of the GenStateMachine. In `:handle_event_function` mode, this can be any term. In `:state_functions` mode, it must be an atom.

```elixir
state() :: state_name() | term()
```

--------------------------------

### Keep state with reply definition

Source: https://hexdocs.pm/gen_state_machine_helpers/index.html

Type specification for the keep_state/2 function.

```elixir
keep_state(any, any) :: {:keep_state, any, any}
```

--------------------------------

### keep_state/1

Source: https://hexdocs.pm/gen_state_machine_helpers/GenStateMachineHelpers.html

Returns the {:keep_state, data} tuple. This function is useful for keeping the current state within a GenStateMachine pipeline.

```APIDOC
## keep_state/1

### Description
Returns the {:keep_state, data} tuple.

### Function Signature
```elixir
keep_state(data) :: {:keep_state, any}
```

### Parameters
- **data** (any) - The data to be kept in the state.

### Request Example
```elixir
GenStateMachineHelpers.keep_state(%{})
```

### Response Example
```elixir
{:keep_state, %{}}
```
```

--------------------------------

### GenStateMachine State Enter Result Type

Source: https://hexdocs.pm/gen_state_machine/GenStateMachine.html

Defines the return type for state enter functions within a GenStateMachine. Consult the Erlang documentation for a complete reference of possible return values.

```elixir
state_enter_result(state) :: :gen_statem.state_enter_result(state)
```
Tokens:
Raw