# Module ra

- Description
- Data Types
- Function Index
- Function Details

The primary module for interacting with ra servers and clusters.

## Description

The primary module for interacting with ra servers and clusters.

## Data Types

### environment_param()

    environment_param() =
        {data_dir, file:filename()} |
        {wal_data_dir, file:filename()} |
        {segment_max_entries, non_neg_integer()} |
        {wal_max_size_bytes, non_neg_integer()} |
        {wal_compute_checksums, boolean()} |
        {wal_write_strategy, default | o_sync}

### query_fun()

    query_fun() =
        fun((term()) -> term()) |
        {M :: module(), F :: atom(), A :: list()}

### ra_cmd_ret()

    ra_cmd_ret() = ra_server_proc:ra_cmd_ret()

## Function Index

start/0 | Starts the ra application.
start/1 | Starts the ra application.
start_in/1 | Starts the ra application with a provided data directory.
restart_server/1 | Restarts a previously succesfully started ra server.
stop_server/1 | Stops a ra server.
force_delete_server/1 | Deletes a ra server The server is forcefully deleted.
start_or_restart_cluster/3 | Starts or restarts a ra cluster.
start_cluster/3 | Starts a new distributed ra cluster.
start_cluster/1 | Starts a new distributed ra cluster.
start_server/4 |
start_server/1 | Starts a ra server.
delete_cluster/1 | Deletes a ra cluster in an orderly fashion This function commits and end of life command which after each server applies it will cause that server to shut down and delete all it's data.
delete_cluster/2 |
add_member/2 | Add a ra server id to a ra cluster's membership configuration This commits a join command to the leader log.
add_member/3 |
remove_member/2 | Removes a server from the cluster's membership configuration This function returns after appending the command to the log.
remove_member/3 |
trigger_election/1 | Causes the server to entre the pre-vote and attempt become leader It is necessary to call this function when starting a new cluster as a branch new ra server will not automatically enter pre-vote by itself.
trigger_election/2 |
leave_and_terminate/1 |
leave_and_terminate/2 |
leave_and_terminate/3 |
leave_and_delete_server/1 |
leave_and_delete_server/2 |
leave_and_delete_server/3 |
new_uid/1 | generates a random uid using the provided source material for the first 6 characters.
overview/0 | return a map of overview data of the ra system on the current erlang node.
process_command/3 | Submits a command to a ra server.
process_command/2 |
pipeline_command/4 | Submits a command to the ra server using a gen_statem:cast passing an optional process scoped term as correlation identifier.
pipeline_command/3 |
pipeline_command/2 | Sends a command to the ra server using a gen_statem:cast.
local_query/2 | Query the machine state on any server This allows you to run the QueryFun over the server machine state and return the result.
local_query/3 |
leader_query/2 | Query the current leader state This function works like local_query, but redirects to the current leader node.
leader_query/3 |
consistent_query/2 | Query the state machine This allows a caller to query the state machine by appending the query to the log and returning the result once applied.
consistent_query/3 |
members/1 | Query the members of a cluster.
members/2 |

## Function Details

### start/0

    start() -> ok

Starts the ra application

### start/1

    start(Params :: [environment_param()]) ->
             {ok, [Started]} | {error, term()}

-     Started = term()

Starts the ra application. If the application is running it will be stopped and restarted.

### start_in/1

    start_in(DataDir :: file:filename()) ->
                {ok, [Started]} | {error, term()}

-     Started = term()

Starts the ra application with a provided data directory. The same as ra:start([{data_dir, dir}]) If the application is running it will be stopped and restarted.

### restart_server/1

    restart_server(ServerId :: ra_server_id()) -> ok | {error, term()}

`ServerId`: the ra_server_id() of the server

returns: `{ok | error, Error}` when error can be `not_found` or `name_not_registered` when the ra server has never before been started on the erlang node.

Restarts a previously succesfully started ra server

### stop_server/1

    stop_server(ServerId :: ra_server_id()) -> ok | {error, nodedown}

`ServerId`: the ra_server_id() of the server

returns: `{ok | error, nodedown}`

Stops a ra server

### force_delete_server/1

    force_delete_server(ServerId :: ra_server_id()) ->
                           ok | {error, term()}

`ServerId`: the ra_server_id() of the server

returns: `{ok | error, nodedown}`

Deletes a ra server The server is forcefully deleted.

### start_or_restart_cluster/3

    start_or_restart_cluster(ClusterName :: ra_cluster_name(),
                             Machine :: ra_server:machine_conf(),
                             RemServers :: [ra_server_id()]) ->
                                {ok,
                                 [ra_server_id()],
                                 [ra_server_id()]} |
                                {error, cluster_not_formed}

`ClusterName`: the name of the cluster.
`Machine`: The `ra_machine:machine/0` configuration.

returns:

`{ok, Started, NotStarted}` if a cluster could be successfully started. A cluster can be successfully started if more than half of the servers provided could be started. Servers that could not be started need to be retried periodically using `start_server/1`

`{error, cluster_not_formed}` if a cluster could not be started.

If there was no existing cluster and a new cluster could not be formed any servers that did manage to start are forcefully deleted.

Starts or restarts a ra cluster.

### start_cluster/3

    start_cluster(ClusterName :: ra_cluster_name(),
                  Machine :: ra_server:machine_conf(),
                  ServerIds :: [ra_server_id()]) ->
                     {ok, [ra_server_id()], [ra_server_id()]} |
                     {error, cluster_not_formed}

`ClusterName`: the name of the cluster.
`Machine`: The `ra_machine:machine/0` configuration.
`ServerIds`: The list of ra server ids.

returns:

`{ok, Started, NotStarted}` if a cluster could be successfully started. A cluster can be successfully started if more than half of the servers provided could be started. Servers that could not be started need to be retried periodically using `start_server/1`

`{error, cluster_not_formed}` if a cluster could not be started.

If a cluster could not be formed any servers that did manage to start are forcefully deleted.

Starts a new distributed ra cluster.

### start_cluster/1

    start_cluster(ServerConfigs :: [ra_server:ra_server_config()]) ->
                     {ok, [ra_server_id()], [ra_server_id()]} |
                     {error, cluster_not_formed}

`ServerConfigs`: a list of initial server configurations

returns:

`{ok, Started, NotStarted}` if a cluster could be successfully started. A cluster can be successfully started if more than half of the servers provided could be started. Servers that could not be started need to be retried periodically using `start_server/1`

`{error, cluster_not_formed}` if a cluster could not be started.

If a cluster could not be formed any servers that did manage to start are forcefully deleted.

Starts a new distributed ra cluster.

### start_server/4

    start_server(ClusterName :: ra_cluster_name(),
                 ServerId :: ra_server_id(),
                 Machine :: ra_server:machine_conf(),
                 ServerIds :: [ra_server_id()]) ->
                    ok | {error, term()}

### start_server/1

    start_server(Conf :: ra_server:ra_server_config()) ->
                    ok | {error, term()}

`Conf`: a ra_server_config() configuration map.

returns: `{ok | error, Error}`

Starts a ra server

### delete_cluster/1

    delete_cluster(ServerIds :: [ra_server_id()]) ->
                      {ok, ra_server_id()} | {error, term()}

`ServerIds`: the ra_server_ids of the cluster

returns: `{ok | error, nodedown}`

Deletes a ra cluster in an orderly fashion This function commits and end of life command which after each server applies it will cause that server to shut down and delete all it's data. The leader will stay up until it has successfully replicated the end of life command to all servers after which it too will shut down and delete all it's data.

### delete_cluster/2

    delete_cluster(ServerIds :: [ra_server_id()],
                   Timeout :: timeout()) ->
                      {ok, Leader :: ra_server_id()} | {error, term()}

See also: delete_cluster/1.

### add_member/2

    add_member(ServerRef :: ra_server_id(),
               ServerId :: ra_server_id()) ->
                  ra_cmd_ret()

`ServerRef`: the ra server to send the command to
`ServerId`: the ra server id of the new server

Add a ra server id to a ra cluster's membership configuration This commits a join command to the leader log. After this has been replicated the leader will start replicating entries to the new server. This function returns after appending the command to the log.

### add_member/3

    add_member(ServerRef :: ra_server_id(),
               ServerId :: ra_server_id(),
               Timeout :: timeout()) ->
                  ra_cmd_ret()

See also: add_member/2.

### remove_member/2

    remove_member(ServerRef :: ra_server_id(),
                  ServerId :: ra_server_id()) ->
                     ra_cmd_ret()

`ServerRef`: the ra server to send the command to
`ServerId`: the ra server id of the server to remove

Removes a server from the cluster's membership configuration This function returns after appending the command to the log.

### remove_member/3

    remove_member(ServerRef :: ra_server_id(),
                  ServerId :: ra_server_id(),
                  Timeout :: timeout()) ->
                     ra_cmd_ret()

See also: remove_member/2.

### trigger_election/1

    trigger_election(ServerId :: ra_server_id()) -> ok

`ServerId`: the ra server id of the server to trigger the election on.

Causes the server to entre the pre-vote and attempt become leader It is necessary to call this function when starting a new cluster as a branch new ra server will not automatically enter pre-vote by itself. Previously started servers will however.

### trigger_election/2

    trigger_election(ServerId :: ra_server_id(), Timeout :: timeout()) ->
                        ok

### leave_and_terminate/1

`leave_and_terminate(ServerId) -> any()`

### leave_and_terminate/2

    leave_and_terminate(ServerRef :: ra_server_id(),
                        ServerId :: ra_server_id()) ->
                           ok | timeout | {error, no_proc}

### leave_and_terminate/3

    leave_and_terminate(ServerRef :: ra_server_id(),
                        ServerId :: ra_server_id(),
                        Timeout :: timeout()) ->
                           ok | timeout | {error, no_proc}

### leave_and_delete_server/1

`leave_and_delete_server(ServerId) -> any()`

### leave_and_delete_server/2

    leave_and_delete_server(ServerRef :: ra_server_id(),
                            ServerId :: ra_server_id()) ->
                               ok | timeout | {error, no_proc}

### leave_and_delete_server/3

    leave_and_delete_server(ServerRef :: ra_server_id(),
                            ServerId :: ra_server_id(),
                            Timeout :: timeout()) ->
                               ok | timeout | {error, no_proc}

### new_uid/1

`new_uid(Source) -> any()`

generates a random uid using the provided source material for the first 6 characters

### overview/0

    overview() -> map()

return a map of overview data of the ra system on the current erlang node.

### process_command/3

    process_command(ServerId :: ra_server_id(),
                    Command :: term(),
                    Timeout :: non_neg_integer()) ->
                       {ok, Reply :: term(), Leader :: ra_server_id()} |
                       {error, term()} |
                       {timeout, ra_server_id()}

`ServerId`: the server id to send the command to
`Command`: an arbitrary term that the state machine can handle
`Timeout`: the time to wait before returning {timeout, ServerId}

Submits a command to a ra server. Returs after the command has been applied to the Raft state machine. If the state machine returned a response it is included in the second element of the response tuple. If the no response was returned the second element is the atom `noreply`. If the server receiving the command isn't the current leader it will redirect the call to the leader if known or hold on to the command until a leader is known. The leader's server id is returned as the 3rd element of the success reply tuple.

### process_command/2

    process_command(ServerId :: ra_server_id(), Command :: term()) ->
                       {ok, Reply :: term(), Leader :: ra_server_id()} |
                       {error, term()} |
                       {timeout, ra_server_id()}

### pipeline_command/4

    pipeline_command(ServerId :: ra_server_id(),
                     Command :: term(),
                     Correlation ::
                         ra_server:command_correlation() |
                         no_correlation,
                     Priority :: normal | low) ->
                        ok

`ServerId`: the ra server id to send the command to
`Command`: an arbitrary term that the state machine can handle
`Correlation`: a correlation identifier to be included to receive an async notification after the command is applied to the state machine. If the Correlation is `no_correlation` no notifications will be sent.
`Priority`: command priority. `low` priority commands will be held back and appended to the Raft log in batches. NB: A `normal` priority command sent from the same process can overtake a low priority command that was sent before. There is no high priority. Only use pritory level `low` for commands where total ordering does not matter.

Submits a command to the ra server using a gen_statem:cast passing an optional process scoped term as correlation identifier. A correlation id can be included to implement reliable async interactions with the ra system. The calling process can retain a map of command that have not yet been applied to the state machine successfully and resend them if a notification is not receied withing some time window. When the command is applied to the state machine the ra server will send the calling process a ra_event of the following structure:

`{ra_event, CurrentLeader, {applied, [{Correlation, Reply}]}}`

Not that ra will batch notification and thus return a list of correlation and result tuples.

If the receving ra server isn't a leader a ra event of the following structure will be returned informing the caller that it cannot process the message including the current leader, if known:

`{ra_event, CurrentLeader, {rejected, {not_leader, Leader, Correlation}}}` The caller can then redirect the command for the correlation identifier to the correct ra server.

If insteads the atom `no_correlation` is used the calling process will not receive any notification of command processing success or otherwise. This is the least reliable way to interact with a ra system and should only be used if the command is of little importance.

### pipeline_command/3

    pipeline_command(ServerId :: ra_server_id(),
                     Command :: term(),
                     Correlation ::
                         ra_server:command_correlation() |
                         no_correlation) ->
                        ok

### pipeline_command/2

    pipeline_command(ServerId :: ra_server_id(), Command :: term()) ->
                        ok

Sends a command to the ra server using a gen_statem:cast. Effectively the same as `ra:pipeline_command(ServerId, Command, low, no_correlation)` This is the least reliable way to interact with a ra system and should only be used for commands that are of little importance and where waiting for a response is prohibitively slow.

### local_query/2

    local_query(ServerId :: ra_server_id(), QueryFun :: query_fun()) ->
                   {ok,
                    {ra_idxterm(), term()},
                    ra_server_id() | not_known}

Query the machine state on any server This allows you to run the QueryFun over the server machine state and return the result. Any ra server can be addressed. This can return infinitely stale results.

### local_query/3

    local_query(ServerId :: ra_server_id(),
                QueryFun :: query_fun(),
                Timeout :: timeout()) ->
                   {ok,
                    {ra_idxterm(), term()},
                    ra_server_id() | not_known}

### leader_query/2

    leader_query(ServerId :: ra_server_id(), QueryFun :: query_fun()) ->
                    {ok,
                     {ra_idxterm(), term()},
                     ra_server_id() | not_known}

Query the current leader state This function works like local_query, but redirects to the current leader node. The leader state may be more up-to-date compared to local. This function may still return stale results as it reads the current state and does not wait for commands to be applied.

### leader_query/3

    leader_query(ServerId :: ra_server_id(),
                 QueryFun :: query_fun(),
                 Timeout :: timeout()) ->
                    {ok,
                     {ra_idxterm(), term()},
                     ra_server_id() | not_known}

### consistent_query/2

    consistent_query(Server :: ra_server_id(),
                     QueryFun :: query_fun()) ->
                        {ok,
                         Reply :: term(),
                         ra_server_id() | not_known}

Query the state machine This allows a caller to query the state machine by appending the query to the log and returning the result once applied. This guarantees the result is consistent.

### consistent_query/3

    consistent_query(Server :: ra_server_id(),
                     QueryFun :: query_fun(),
                     Timeout :: timeout()) ->
                        {ok,
                         Reply :: term(),
                         ra_server_id() | not_known}

### members/1

    members(ServerRef :: ra_server_id()) ->
               ra_server_proc:ra_leader_call_ret([ra_server_id()])

Query the members of a cluster

### members/2

    members(ServerRef :: ra_server_id(), Timeout :: timeout()) ->
               ra_server_proc:ra_leader_call_ret([ra_server_id()])

Generated by EDoc