Module ra

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}

index()

index() = ra_index()

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()

server_id()

server_id() = ra_server_id()

Function Index

add_member/2Add 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/2Query 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/1Deletes 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/1Deletes a ra server The server is forcefully deleted.
leader_query/2Query 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/2Query 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/1Query the members of a cluster.
members/2
new_uid/1generates a random uid using the provided source material for the first 6 characters.
overview/0return a map of overview data of the ra system on the current erlang node.
pipeline_command/2Sends a command to the ra server using a gen_statem:cast.
pipeline_command/3
pipeline_command/4Submits 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/3Submits a command to a ra server.
remove_member/2Removes a server from the cluster's membership configuration This function returns after appending the command to the log.
remove_member/3
restart_server/1Restarts a previously succesfully started ra server.
start/0Starts the ra application.
start/1Starts the ra application.
start_cluster/1Starts a new distributed ra cluster.
start_cluster/2
start_cluster/3Starts a new distributed ra cluster.
start_cluster/4Starts a new distributed ra cluster.
start_in/1Starts the ra application with a provided data directory.
start_or_restart_cluster/3Starts or restarts a ra cluster.
start_or_restart_cluster/4
start_server/1Starts a ra server.
start_server/4
stop_server/1Stops a ra server.
transfer_leadership/2
trigger_election/1Causes 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

Function Details

add_member/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/3

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/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/3

consistent_query(Server::ra_server_id(), QueryFun::query_fun(), Timeout::timeout()) -> ra_server_proc:ra_leader_call_ret(term())

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, 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/2

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

See also: delete_cluster/1.

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.

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}

leave_and_delete_server/1

leave_and_delete_server(ServerLoc) -> any()

leave_and_delete_server/2

leave_and_delete_server(ServerLoc::ra_server_id() | [ra_server_id()], ServerId::ra_server_id()) -> ok | timeout | {error, noproc}

leave_and_delete_server/3

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

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, noproc}

leave_and_terminate/3

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

local_query/2

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/3

local_query(ServerId::ra_server_id(), QueryFun::query_fun(), Timeout::timeout()) -> ra_server_proc:ra_leader_call_ret({ra_idxterm(), term()})

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()])

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.

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.

pipeline_command/3

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

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.

process_command/2

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/3

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/2

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/3

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/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

start/0

start() -> ok

Starts the ra application

start/1

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/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_cluster/2

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/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/4

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.

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

Starts a new distributed ra cluster.

start_in/1

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/3

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.

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_or_restart_cluster/4

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.

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

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

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()}

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

transfer_leadership/2

transfer_leadership(ServerId::ra_server_id(), TargetServerId::ra_server_id()) -> ok | already_leader

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


Generated by EDoc