Unverified Commit 6ca56090 authored by Ozan Tezcan's avatar Ozan Tezcan Committed by GitHub
Browse files

Documentation fixes (#142)



Documentation fixes
Co-authored-by: default avatarHanna Fadida <hanna.fadida@redislabs.com>
parent 5d42a923
...@@ -497,7 +497,6 @@ typedef int ( ...@@ -497,7 +497,6 @@ typedef int (
/** Callback for determining which node this configuration log entry /** Callback for determining which node this configuration log entry
* affects. This call only applies to configuration change log entries. * affects. This call only applies to configuration change log entries.
* @return the node ID of the node
* *
* @param[in] raft The Raft server making this callback * @param[in] raft The Raft server making this callback
* @param[in] user_data User data that is passed from Raft server * @param[in] user_data User data that is passed from Raft server
...@@ -817,7 +816,8 @@ typedef struct raft_log_impl ...@@ -817,7 +816,8 @@ typedef struct raft_log_impl
/** Remove entries from the start of the log, as necessary when compacting /** Remove entries from the start of the log, as necessary when compacting
* the log and deleting the oldest entries. * the log and deleting the oldest entries.
* *
* The log implementation must call raft_entry_release() on any removed in-memory entries * The log implementation must call raft_entry_release() on any removed
* in-memory entries.
* *
* @param[in] first_idx Index of first entry to be left in log. * @param[in] first_idx Index of first entry to be left in log.
* @return * @return
...@@ -829,7 +829,8 @@ typedef struct raft_log_impl ...@@ -829,7 +829,8 @@ typedef struct raft_log_impl
/** Remove entries from the end of the log, as necessary when rolling back /** Remove entries from the end of the log, as necessary when rolling back
* append operations that have not been committed. * append operations that have not been committed.
* *
* The log implementation must call raft_entry_release() on any removed in-memory entries * The log implementation must call raft_entry_release() on any removed
* in-memory entries
* *
* @param[in] from_idx Index of first entry to be removed. All entries * @param[in] from_idx Index of first entry to be removed. All entries
* starting from and including this index shall be removed. * starting from and including this index shall be removed.
...@@ -926,7 +927,12 @@ void raft_clear(raft_server_t* me); ...@@ -926,7 +927,12 @@ void raft_clear(raft_server_t* me);
* *
* On a restart, the application should set term and vote after reading metadata * On a restart, the application should set term and vote after reading metadata
* file from the disk. See `raft_persist_metadata_f`. * file from the disk. See `raft_persist_metadata_f`.
**/ *
* @param[in] raft The Raft server
* @param[in] term term in the metadata file
* @param[in] vote vote in the metadata file
* @return 0 on success
*/
int raft_restore_metadata(raft_server_t *me, int raft_restore_metadata(raft_server_t *me,
raft_term_t term, raft_term_t term,
raft_node_id_t vote); raft_node_id_t vote);
...@@ -941,10 +947,6 @@ void raft_set_callbacks(raft_server_t* me, raft_cbs_t* funcs, void* user_data); ...@@ -941,10 +947,6 @@ void raft_set_callbacks(raft_server_t* me, raft_cbs_t* funcs, void* user_data);
* *
* If a voting node already exists the call will fail. * If a voting node already exists the call will fail.
* *
* @note The order this call is made is important.
* This call MUST be made in the same order as the other raft nodes.
* This is because the node ID is assigned depending on when this call is made
*
* @param[in] user_data The user data for the node. * @param[in] user_data The user data for the node.
* This is obtained using raft_node_get_udata. * This is obtained using raft_node_get_udata.
* Examples of what this could be: * Examples of what this could be:
...@@ -1318,8 +1320,10 @@ int raft_begin_load_snapshot(raft_server_t *me, ...@@ -1318,8 +1320,10 @@ int raft_begin_load_snapshot(raft_server_t *me,
**/ **/
int raft_end_load_snapshot(raft_server_t *me); int raft_end_load_snapshot(raft_server_t *me);
/** Return last applied entry index that snapshot includes. */
raft_index_t raft_get_snapshot_last_idx(raft_server_t *me); raft_index_t raft_get_snapshot_last_idx(raft_server_t *me);
/** Return last applied entry term that snapshot includes. */
raft_term_t raft_get_snapshot_last_term(raft_server_t *me); raft_term_t raft_get_snapshot_last_term(raft_server_t *me);
/** Check if a node's voting status has been committed. /** Check if a node's voting status has been committed.
...@@ -1374,6 +1378,7 @@ void raft_entry_release(raft_entry_t *ety); ...@@ -1374,6 +1378,7 @@ void raft_entry_release(raft_entry_t *ety);
* *
* @note The array itself is not freed. * @note The array itself is not freed.
*/ */
void raft_entry_release_list(raft_entry_t **ety_list, size_t len); void raft_entry_release_list(raft_entry_t **ety_list, size_t len);
/** Log Implementation callbacks structure for the default in-memory /** Log Implementation callbacks structure for the default in-memory
...@@ -1381,6 +1386,14 @@ void raft_entry_release_list(raft_entry_t **ety_list, size_t len); ...@@ -1381,6 +1386,14 @@ void raft_entry_release_list(raft_entry_t **ety_list, size_t len);
*/ */
extern const raft_log_impl_t raft_log_internal_impl; extern const raft_log_impl_t raft_log_internal_impl;
/** Enqueue a readonly request
*
* @param[in] me The Raft server
* @param[in] cb Function to be called when it is safe to execute the request
* @param[in] cb_arg User argument to the callback
* @return 0 on success
* RAFT_ERR_NOT_LEADER server is not the leader
*/
int raft_recv_read_request(raft_server_t* me, raft_read_request_callback_f cb, void *cb_arg); int raft_recv_read_request(raft_server_t* me, raft_read_request_callback_f cb, void *cb_arg);
/** Invoke a leadership transfer to targeted node /** Invoke a leadership transfer to targeted node
...@@ -1389,17 +1402,39 @@ int raft_recv_read_request(raft_server_t* me, raft_read_request_callback_f cb, v ...@@ -1389,17 +1402,39 @@ int raft_recv_read_request(raft_server_t* me, raft_read_request_callback_f cb, v
* selection. Node with the most entries will be selected. * selection. Node with the most entries will be selected.
* @param[in] timeout timeout in ms before this transfer is aborted. * @param[in] timeout timeout in ms before this transfer is aborted.
* if 0, use default election timeout * if 0, use default election timeout
* @return an error if leadership transfer is already in progress or * @return 0 on success
* the targeted node_id is unknown * RAFT_ERR_NOT_LEADER server is not the leader.
* RAFT_ERR_LEADER_TRANSFER_IN_PROGRESS if leadership transfer is
* already in progress.
* RAFT_ERR_INVALID_NODEID target node ID is unknown.
*/ */
int raft_transfer_leader(raft_server_t* me, raft_node_id_t node_id, long timeout); int raft_transfer_leader(raft_server_t* me, raft_node_id_t node_id, long timeout);
/* get the targeted node_id if a leadership transfer is in progress, or RAFT_NODE_ID_NONE if not */ /** Return leader transfer target node id
*
* @param[in] me The Raft server
* @return target node id if leadership transfer is in progress, or
* RAFT_NODE_ID_NONE otherwise
*/
raft_node_id_t raft_get_transfer_leader(raft_server_t *me); raft_node_id_t raft_get_transfer_leader(raft_server_t *me);
/* cause this server to force an election. */ /** Force this server to start an election
*
* As the last step of leader transfer, current leader calls
* `raft_send_timeoutnow_f` to send a message to the target node. Target node
* should start an election by calling this function when it receives timeoutnow
* message.
*
* @param[in] me The Raft server
* @return 0 on success, non-zero otherwise
*/
int raft_timeout_now(raft_server_t* me); int raft_timeout_now(raft_server_t* me);
/** Return number of entries that can be compacted
*
* @param[in] me The Raft server
* @return number of entries that can be compacted
*/
raft_index_t raft_get_num_snapshottable_logs(raft_server_t* me); raft_index_t raft_get_num_snapshottable_logs(raft_server_t* me);
/** /**
...@@ -1470,7 +1505,7 @@ int raft_flush(raft_server_t* me, raft_index_t sync_index); ...@@ -1470,7 +1505,7 @@ int raft_flush(raft_server_t* me, raft_index_t sync_index);
* synchronous. sync() callback is called when an appendentries message * synchronous. sync() callback is called when an appendentries message
* received. So, this function does not makes sense if the node is a follower. * received. So, this function does not makes sense if the node is a follower.
* *
* @param[in] raft The Raft server * @param[in] me The Raft server
* @return entry index need to be written to the disk. * @return entry index need to be written to the disk.
* '0' if there is no new entry to write to the disk * '0' if there is no new entry to write to the disk
*/ */
...@@ -1506,9 +1541,9 @@ raft_index_t raft_get_index_to_sync(raft_server_t *me); ...@@ -1506,9 +1541,9 @@ raft_index_t raft_get_index_to_sync(raft_server_t *me);
* int election_timeout; * int election_timeout;
* raft_config(raft, 0, RAFT_CONFIG_ELECTION_TIMEOUT, &election_timeout); * raft_config(raft, 0, RAFT_CONFIG_ELECTION_TIMEOUT, &election_timeout);
* *
* @param set 1 to set the value, 0 to get the current value. * @param[in] set 1 to set the value, 0 to get the current value.
* @param config Config enum. * @param[in] config Config enum.
* @param ... Value to set or destination variable to get the config. * @param[in] ... Value to set or destination variable to get the config.
* @return 0 on success, RAFT_ERR_NOTFOUND if config is missing. * @return 0 on success, RAFT_ERR_NOTFOUND if config is missing.
*/ */
int raft_config(raft_server_t *me, int set, raft_config_e config, ...); int raft_config(raft_server_t *me, int set, raft_config_e config, ...);
...@@ -1522,7 +1557,7 @@ int raft_config(raft_server_t *me, int set, raft_config_e config, ...); ...@@ -1522,7 +1557,7 @@ int raft_config(raft_server_t *me, int set, raft_config_e config, ...);
* messages and execute long running batch of operations without affecting * messages and execute long running batch of operations without affecting
* cluster availability. * cluster availability.
* *
* @param[in] raft The Raft server * @param[in] me The Raft server
* @return 0 if there is no pending operations, non-zero otherwise. * @return 0 if there is no pending operations, non-zero otherwise.
*/ */
int raft_pending_operations(raft_server_t *me); int raft_pending_operations(raft_server_t *me);
...@@ -1532,6 +1567,10 @@ int raft_pending_operations(raft_server_t *me); ...@@ -1532,6 +1567,10 @@ int raft_pending_operations(raft_server_t *me);
* This function should only be called after a restart. After application loads * This function should only be called after a restart. After application loads
* the snapshot and log entries, this function should be called to rebuild * the snapshot and log entries, this function should be called to rebuild
* cluster configuration from the logs. * cluster configuration from the logs.
*
* @param[in] raft The Raft server
* @return 0 on success
* RAFT_ERR_MISUSE if a misuse detected.
*/ */
int raft_restore_log(raft_server_t *me); int raft_restore_log(raft_server_t *me);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment