diff --git a/include/raft.h b/include/raft.h index 5da6435c..865bda8f 100644 --- a/include/raft.h +++ b/include/raft.h @@ -206,7 +206,7 @@ typedef int ( ); /** Callback for saving who we voted for to disk. - * This callback MUST flush the change to disk. + * For safety reasons this callback MUST flush the change to disk. * @param[in] raft The Raft server making this callback * @param[in] user_data User data that is passed from Raft server * @param[in] voted_for The node we voted for @@ -220,16 +220,21 @@ typedef int ( ); /** Callback for saving log entry changes. + * * This callback is used for: * - * This callback MUST flush the change to disk. + * + * For safety reasons this callback MUST flush the change to disk. + * * @param[in] raft The Raft server making this callback * @param[in] user_data User data that is passed from Raft server - * @param[in] entry The entry that the event is happening to + * @param[in] entry The entry that the event is happening to. + * The user is allowed to change the memory pointed to in the + * raft_entry_data_t struct. This MUST be done if the memory is temporary. * @param[in] entry_idx The entries index in the log * @return 0 on success */ typedef int ( @@ -253,23 +258,27 @@ typedef struct func_applylog_f applylog; /** Callback for persisting vote data - * This callback MUST flush the change to disk. */ + * For safety reasons this callback MUST flush the change to disk. */ func_persist_int_f persist_vote; /** Callback for persisting term data - * This callback MUST flush the change to disk. */ + * For safety reasons this callback MUST flush the change to disk. */ func_persist_int_f persist_term; /** Callback for adding an entry to the log - * This callback MUST flush the change to disk. */ + * For safety reasons this callback MUST flush the change to disk. */ func_logentry_event_f log_offer; /** Callback for removing the oldest entry from the log - * This callback MUST flush the change to disk. */ + * For safety reasons this callback MUST flush the change to disk. + * @note If memory was malloc'd in log_offer then this should be the right + * time to free the memory. */ func_logentry_event_f log_poll; /** Callback for removing the youngest entry from the log - * This callback MUST flush the change to disk. */ + * For safety reasons this callback MUST flush the change to disk. + * @note If memory was malloc'd in log_offer then this should be the right + * time to free the memory. */ func_logentry_event_f log_pop; /** Callback for catching debugging log messages @@ -318,11 +327,11 @@ __attribute__ ((deprecated)); /** Add node. * * @note This library does not yet support membership changes. - * Once raft_periodic has been run this will fail. + * Once raft_periodic has been run this 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 + * 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. * This is obtained using raft_node_get_udata. @@ -351,7 +360,18 @@ void raft_set_request_timeout(raft_server_t* me, int msec); int raft_periodic(raft_server_t* me, int msec_elapsed); /** Receive an appendentries message. - * This function will block if it needs to append the message. + * + * Will block (ie. by syncing to disk) if we need to append a message. + * + * Might call malloc once to increase the log entry array size. + * + * The log_offer callback will be called. + * + * @note The memory pointer (ie. raft_entry_data_t) for each msg_entry_t is + * copied directly. If the memory is temporary you MUST either make the + * memory permanent (ie. via malloc) OR re-assign the memory within the + * log_offer callback. + * * @param[in] node Index of the node who sent us this message * @param[in] ae The appendentries message * @param[out] r The resulting response @@ -387,11 +407,20 @@ int raft_recv_requestvote_response(raft_server_t* me, int node, msg_requestvote_response_t* r); -/** Receive an entry message from client. +/** Receive an entry message from the client. * * Append the entry to the log and send appendentries to followers. * - * This function will block if it needs to append the message. + * Will block (ie. by syncing to disk) if we need to append a message. + * + * Might call malloc once to increase the log entry array size. + * + * The log_offer callback will be called. + * + * @note The memory pointer (ie. raft_entry_data_t) in msg_entry_t is + * copied directly. If the memory is temporary you MUST either make the + * memory permanent (ie. via malloc) OR re-assign the memory within the + * log_offer callback. * * Will fail: *