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}
index() = ra_index()
query_fun() = fun((term()) -> term()) | {M::module(), F::atom(), A::list()}
ra_cmd_ret() = ra_server_proc:ra_cmd_ret()
server_id() = ra_server_id()
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 | |
consistent_query/2 | Query the state machine This allows a caller to query the state machine on the leader node with an additional heartbeat to check that the node is still the leader. |
consistent_query/3 | |
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 | |
force_delete_server/1 | Deletes a ra server The server is forcefully deleted. |
leader_query/2 | Query the current leader state This function works like local_query, but redirects to the current leader node. |
leader_query/3 | |
leave_and_delete_server/1 | |
leave_and_delete_server/2 | |
leave_and_delete_server/3 | |
leave_and_terminate/1 | |
leave_and_terminate/2 | |
leave_and_terminate/3 | |
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 | |
members/1 | Query the members of a cluster. |
members/2 | |
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. |
pipeline_command/2 | Sends a command to the ra server using a gen_statem:cast. |
pipeline_command/3 | |
pipeline_command/4 | Submits a command to the ra server using a gen_statem:cast passing an optional process scoped term as correlation identifier. |
process_command/2 | |
process_command/3 | Submits a command to a ra server. |
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 | |
restart_server/1 | Restarts a previously succesfully started ra server. |
start/0 | Starts the ra application. |
start/1 | Starts the ra application. |
start_cluster/1 | Starts a new distributed ra cluster. |
start_cluster/2 | |
start_cluster/3 | Starts a new distributed ra cluster. |
start_cluster/4 | Starts a new distributed ra cluster. |
start_in/1 | Starts the ra application with a provided data directory. |
start_or_restart_cluster/3 | Starts or restarts a ra cluster. |
start_or_restart_cluster/4 | |
start_server/1 | Starts a ra server. |
start_server/4 | |
stop_server/1 | Stops a ra server. |
transfer_leadership/2 | |
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 |
add_member(ServerLoc::ra_server_id() | [ra_server_id()], ServerId::ra_server_id()) -> ra_cmd_ret()
ServerLoc: the ra server or servers to try 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(ServerLoc::ra_server_id() | [ra_server_id()], ServerId::ra_server_id(), Timeout::timeout()) -> ra_cmd_ret()
See also: add_member/2.
consistent_query(Server::ra_server_id(), QueryFun::query_fun()) -> ra_server_proc:ra_leader_call_ret(term())
Query the state machine This allows a caller to query the state machine on the leader node with an additional heartbeat to check that the node is still the leader. Consistency guarantee is that the query will return result containing at least all changes, committed before this query is issued. This may include changes which were committed while the query is running.
consistent_query(Server::ra_server_id(), QueryFun::query_fun(), Timeout::timeout()) -> ra_server_proc:ra_leader_call_ret(term())
delete_cluster(ServerIds::[ra_server_id()]) -> {ok, ra_server_id()} | {error, term()}
ServerIds: the ra_server_ids of the cluster
returns: {{ok, Leader} | 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(ServerIds::[ra_server_id()], Timeout::timeout()) -> {ok, Leader::ra_server_id()} | {error, term()}
See also: delete_cluster/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.
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(ServerId::ra_server_id(), QueryFun::query_fun(), Timeout::timeout()) -> {ok, {ra_idxterm(), term()}, ra_server_id() | not_known}
leave_and_delete_server(ServerLoc) -> any()
leave_and_delete_server(ServerLoc::ra_server_id() | [ra_server_id()], ServerId::ra_server_id()) -> ok | timeout | {error, noproc}
leave_and_delete_server(ServerRef::ra_server_id() | [ra_server_id()], ServerId::ra_server_id(), Timeout::timeout()) -> ok | timeout | {error, noproc}
leave_and_terminate(ServerId) -> any()
leave_and_terminate(ServerRef::ra_server_id(), ServerId::ra_server_id()) -> ok | timeout | {error, noproc}
leave_and_terminate(ServerRef::ra_server_id(), ServerId::ra_server_id(), Timeout::timeout()) -> ok | timeout | {error, noproc}
local_query(ServerId::ra_server_id(), QueryFun::query_fun()) -> ra_server_proc:ra_leader_call_ret({ra_idxterm(), term()})
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(ServerId::ra_server_id(), QueryFun::query_fun(), Timeout::timeout()) -> ra_server_proc:ra_leader_call_ret({ra_idxterm(), term()})
members(ServerRef::ra_server_id()) -> ra_server_proc:ra_leader_call_ret([ra_server_id()])
Query the members of a cluster
members(ServerRef::ra_server_id(), Timeout::timeout()) -> ra_server_proc:ra_leader_call_ret([ra_server_id()])
new_uid(Source) -> any()
generates a random uid using the provided source material for the first 6 characters
overview() -> map()
return a map of overview data of the ra system on the current erlang node.
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.
pipeline_command(ServerId::ra_server_id(), Command::term(), Correlation::ra_server:command_correlation() | no_correlation) -> ok
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.
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.
process_command(ServerLoc::ra_server_id() | [ra_server_id()], Command::term()) -> {ok, Reply::term(), Leader::ra_server_id()} | {error, term()} | {timeout, ra_server_id()}
process_command(ServerLoc::ra_server_id() | [ra_server_id()], Command::term(), Timeout::non_neg_integer()) -> {ok, Reply::term(), Leader::ra_server_id()} | {error, term()} | {timeout, ra_server_id()}
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.
remove_member(ServerLoc::ra_server_id() | [ra_server_id()], ServerId::ra_server_id()) -> ra_cmd_ret()
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(ServerLoc::ra_server_id() | [ra_server_id()], ServerId::ra_server_id(), Timeout::timeout()) -> ra_cmd_ret()
See also: remove_member/2.
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
start() -> ok
Starts the ra application
start(Params::[environment_param()]) -> {ok, [Started]} | {error, term()}
Starts the ra application. If the application is running it will be stopped and restarted.
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.
Starts a new distributed ra cluster.
start_cluster(ServerConfigs::[ra_server:ra_server_config()], Timeout::non_neg_integer()) -> {ok, [ra_server_id()], [ra_server_id()]} | {error, cluster_not_formed}
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.
Starts a new distributed ra cluster.
start_cluster(ClusterName::ra_cluster_name(), Machine::ra_server:machine_conf(), ServerIds::[ra_server_id()], Timeout::non_neg_integer()) -> {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.
Timeout: The time to wait for each server to start
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.
Starts a new distributed ra cluster.
start_in(DataDir::file:filename()) -> {ok, [Started]} | {error, 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.
start_or_restart_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.
Starts or restarts a ra cluster.
start_or_restart_cluster(ClusterName::ra_cluster_name(), Machine::ra_server:machine_conf(), RemServers::[ra_server_id()], Timeout::non_neg_integer()) -> {ok, [ra_server_id()], [ra_server_id()]} | {error, cluster_not_formed}
ClusterName: the name of the cluster.
Machine: The ra_machine:machine/0
configuration.
Timeout: The time to wait for any server to restart or start
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.
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
start_server(ClusterName::ra_cluster_name(), ServerId::ra_server_id(), Machine::ra_server:machine_conf(), ServerIds::[ra_server_id()]) -> ok | {error, term()}
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
transfer_leadership(ServerId::ra_server_id(), TargetServerId::ra_server_id()) -> ok | already_leader
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(ServerId::ra_server_id(), Timeout::timeout()) -> ok
Generated by EDoc