#include <corosync/corotypes.h>

Include dependency graph for sam.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef int(*	sam_hc_callback_t) (void)
	Callback definition for event driven checking.

Enumerations
enum	sam_recovery_policy_t { SAM_RECOVERY_POLICY_QUIT = 1 , SAM_RECOVERY_POLICY_RESTART = 2 , SAM_RECOVERY_POLICY_QUORUM = 0x08 , SAM_RECOVERY_POLICY_QUORUM_QUIT = SAM_RECOVERY_POLICY_QUORUM \| SAM_RECOVERY_POLICY_QUIT , SAM_RECOVERY_POLICY_QUORUM_RESTART = SAM_RECOVERY_POLICY_QUORUM \| SAM_RECOVERY_POLICY_RESTART , SAM_RECOVERY_POLICY_CMAP = 0x10 , SAM_RECOVERY_POLICY_CONFDB = 0x10 }
	sam_recovery_policy_t enum More...

Functions
cs_error_t	sam_initialize (int time_interval, sam_recovery_policy_t recovery_policy)
	Create a new SAM connection.

cs_error_t	sam_finalize (void)
	Close the SAM handle.

cs_error_t	sam_start (void)
	Start healthchecking.

cs_error_t	sam_stop (void)
	Stop healthchecking.

cs_error_t	sam_warn_signal_set (int warn_signal)
	Set warning signal to be sent.

cs_error_t	sam_register (unsigned int *instance_id)
	Register application.

cs_error_t	sam_hc_send (void)
	Send healthcheck confirmation.

cs_error_t	sam_hc_callback_register (sam_hc_callback_t cb)
	Register healtcheck callback.

cs_error_t	sam_data_getsize (size_t *size)
	Return size of stored data.

cs_error_t	sam_data_restore (void *data, size_t size)
	Return stored data.

cs_error_t	sam_data_store (const void *data, size_t size)
	Store user data.

cs_error_t	sam_mark_failed (void)
	Marks child as failed.

Typedef Documentation

◆ sam_hc_callback_t

typedef int(* sam_hc_callback_t) (void)

Callback definition for event driven checking.

Definition at line 59 of file sam.h.

Enumeration Type Documentation

◆ sam_recovery_policy_t

enum sam_recovery_policy_t

sam_recovery_policy_t enum

Enumerator
SAM_RECOVERY_POLICY_QUIT
SAM_RECOVERY_POLICY_RESTART
SAM_RECOVERY_POLICY_QUORUM
SAM_RECOVERY_POLICY_QUORUM_QUIT
SAM_RECOVERY_POLICY_QUORUM_RESTART
SAM_RECOVERY_POLICY_CMAP
SAM_RECOVERY_POLICY_CONFDB

Definition at line 46 of file sam.h.

Function Documentation

◆ sam_data_getsize()

cs_error_t sam_data_getsize ( size_t * size )

Return size of stored data.

Parameters

size	Pointer to variable, where stored data size is returned. If nothing or NULL is stored, then 0 is returned.

Return values

CS_OK	in case no problem appeared
CS_ERR_BAD_HANDLE	in case you call this function before sam_init or after sam_finalize
CS_ERR_INVALID_PARAM	if size parameter is NULL

Definition at line 431 of file sam.c.

References CS_ERR_BAD_HANDLE, CS_ERR_INVALID_PARAM, CS_OK, nodeid, SAM_INTERNAL_STATUS_INITIALIZED, SAM_INTERNAL_STATUS_REGISTERED, and SAM_INTERNAL_STATUS_STARTED.

◆ sam_data_restore()

cs_error_t sam_data_restore	(	void *	data,
		size_t	size
	)

Return stored data.

Parameters

data	Pointer to place, where to store data
size	Allocated size of data

Return values

CS_OK	if no problem appeared
CS_ERR_BAD_HANDLE	if you call this function before sam_init or after sam_finalize
CS_ERR_INVALID_PARAM	if data is NULL or size is less then currently saved user data length

Definition at line 453 of file sam.c.

References CS_ERR_BAD_HANDLE, CS_ERR_INVALID_PARAM, CS_OK, nodeid, SAM_INTERNAL_STATUS_INITIALIZED, SAM_INTERNAL_STATUS_REGISTERED, and SAM_INTERNAL_STATUS_STARTED.

◆ sam_data_store()

cs_error_t sam_data_store	(	const void *	data,
		size_t	size
	)

Store user data.

Such stored data survives restart of child.

Parameters

data	Data to store. You can use NULL to delete data
size	Size of data to store.

Return values

CS_OK	in case no problem appeared
CS_ERR_BAD_HANDLE	if you call this function before sam_init or after sam_finalize
CS_ERR_NO_MEMORY	if data is too large and malloc/realloc was not succesfull
CS_ERR_LIBRARY	if some internal error appeared (communication with parent process)

Definition at line 498 of file sam.c.

References CS_ERR_BAD_HANDLE, CS_ERR_LIBRARY, CS_ERR_NO_MEMORY, CS_OK, nodeid, SAM_COMMAND_DATA_STORE, SAM_INTERNAL_STATUS_INITIALIZED, SAM_INTERNAL_STATUS_REGISTERED, and SAM_INTERNAL_STATUS_STARTED.

◆ sam_finalize()

cs_error_t sam_finalize ( void )

Close the SAM handle.

This function should be called as late as possible. (in reality, if you plan just quit, and checking is stopped, there is no need to call it). Function will stop healtchecking and put library to state, where no new start is possible.

Return values

CS_OK	in case no problem appeared
CS_ERR_BAD_HANDLE	library was not initialized by sam_initialize

Definition at line 696 of file sam.c.

References CS_ERR_BAD_HANDLE, CS_OK, nodeid, SAM_INTERNAL_STATUS_FINALIZED, SAM_INTERNAL_STATUS_INITIALIZED, SAM_INTERNAL_STATUS_REGISTERED, SAM_INTERNAL_STATUS_STARTED, and sam_stop().

◆ sam_hc_callback_register()

cs_error_t sam_hc_callback_register ( sam_hc_callback_t cb )

Register healtcheck callback.

After you will call this function, and set cb to something else then NULL, SAM is automatically switched from application driven healtchecking to event driven healtchecking. In other words, is not longer needed to call sam_hc_send, but your callback function must return 0 in case of healtchecking is correct, or value different then 0, in case something happend. After next hc iteration, warning signal and after that kill signal is sent back to your application.

Parameters

cb	Pointer to healtcheck function, or NULL to switch back to application driven hc

Return values

CS_OK	in case no problem appeared
CS_ERR_BAD_HANDLE	in case, you call this function before sam_init or after sam_start
CS_ERR_LIBRARY	internal library call failed. This can be one of pipe or pthread creation.

Definition at line 1406 of file sam.c.

References CS_ERR_BAD_HANDLE, CS_ERR_INVALID_PARAM, CS_ERR_LIBRARY, CS_OK, nodeid, and SAM_INTERNAL_STATUS_REGISTERED.

◆ sam_hc_send()

cs_error_t sam_hc_send ( void )

Send healthcheck confirmation.

This should be called after sam_start

Return values

CS_OK	in case no problem appeared
CS_ERR_BAD_HANDLE	healthchecking is not in running state (no sam_start was called, or called after sam_stop/sam_finalize)

Definition at line 680 of file sam.c.

References CS_ERR_BAD_HANDLE, CS_ERR_LIBRARY, CS_OK, nodeid, SAM_COMMAND_HB, and SAM_INTERNAL_STATUS_STARTED.

◆ sam_initialize()

cs_error_t sam_initialize	(	int	time_interval,
		sam_recovery_policy_t	recovery_policy
	)

Create a new SAM connection.

This function must be called before any other. It is recommended to call it as one of first in application.

Parameters

time_interval	Time interval in milliseconds of healthcheck. After this time, application will be killed and recovery policy will be taken. This can be zero, which means, that there is no time limit (only fall of application is checked and only then recovery action is taken)
recovery_policy	One of SAM_RECOVERY_POLICY_RESTART, which means, that after timeout application will be killed and new instance will be started. SAM_RECOVERY_POLICY_QUIT will just stop application

Return values

CS_OK	in case no problem appeared
CS_ERR_BAD_HANDLE	in case user is trying to initialize initialized instance
CS_ERR_INVALID_PARAM	in case recovery_policy had bad value

Definition at line 275 of file sam.c.

References CS_DISPATCH_ONE, CS_ERR_BAD_HANDLE, CS_ERR_INVALID_PARAM, CS_OK, CS_TRACK_CHANGES, nodeid, quorum_dispatch(), quorum_fd_get(), quorum_finalize(), quorum_initialize(), quorum_callbacks_t::quorum_notify_fn, quorum_trackstart(), recovery_policy, SAM_INTERNAL_STATUS_INITIALIZED, SAM_INTERNAL_STATUS_NOT_INITIALIZED, SAM_RECOVERY_POLICY_QUIT, SAM_RECOVERY_POLICY_QUORUM, SAM_RECOVERY_POLICY_RESTART, SAM_RP_MASK, and time_interval.

◆ sam_mark_failed()

cs_error_t sam_mark_failed ( void )

Marks child as failed.

This can be called only with SAM_RECOVERY_POLICY_CMAP flag set and makes sense only for SAM_RECOVERY_POLICY_RESTART. This will kill child without sending warning signal. Cmap state key will be set to failed.

Return values

CS_OK	in case no problem appeared
CS_ERR_BAD_HANDLE	library was not initialized or was already finalized
CS_ERR_INVALID_PARAM	recovery policy doesn't have SAM_RECOVERY_POLICY_CMAP flag set
CS_ERR_LIBRARY	if some internal error appeared (communication with parent process)

Definition at line 720 of file sam.c.

References CS_ERR_BAD_HANDLE, CS_ERR_INVALID_PARAM, CS_ERR_LIBRARY, CS_OK, nodeid, SAM_COMMAND_MARK_FAILED, SAM_INTERNAL_STATUS_REGISTERED, SAM_INTERNAL_STATUS_STARTED, and SAM_RECOVERY_POLICY_CMAP.

◆ sam_register()

cs_error_t sam_register ( unsigned int * instance_id )

Register application.

This is one of most crucial function. In case, your application will be restarted, you will always return to point after calling this function. This function can be called only once, and SAM must be initialized by sam_initialize. You can choose any place in your application, where to call this function.

Parameters

instance_id NULL or pointer to int memory, where current instance of application will be returned. It's always safe to suppose, that first instance (this means, no recovery action was taken yet) will be always 1 and instance_id will be raising up to MAX_INT (after this, it will fall to 0).

Return values

CS_OK	in case no problem appeared
CS_ERR_BAD_HANDLE	in case, you call this function twice, or before sam_init
CS_ERR_LIBRARY	internal library call failed. This can be one of pipe or fork creation. You can get more information from errno

Definition at line 1203 of file sam.c.

References CS_ERR_BAD_HANDLE, CS_ERR_LIBRARY, CS_OK, instance_id, nodeid, quorum_finalize(), SAM_CMAP_KEY_STATE, SAM_CMAP_S_FAILED, SAM_CMAP_S_REGISTERED, SAM_INTERNAL_STATUS_INITIALIZED, SAM_INTERNAL_STATUS_REGISTERED, SAM_PARENT_ACTION_ERROR, SAM_PARENT_ACTION_QUIT, SAM_PARENT_ACTION_RECOVERY, SAM_RECOVERY_POLICY_CMAP, SAM_RECOVERY_POLICY_QUIT, SAM_RECOVERY_POLICY_QUORUM, and SAM_RP_MASK.

◆ sam_start()

cs_error_t sam_start ( void )

Start healthchecking.

From this time, you should call every time_interval sam_hc_send, otherwise, recovery action will be taken.

Return values

CS_OK	in case no problem appeared
CS_ERR_BAD_HANDLE	component was not registered by sam_register

Definition at line 587 of file sam.c.

References CS_ERR_BAD_HANDLE, CS_ERR_LIBRARY, CS_OK, nodeid, SAM_COMMAND_START, SAM_INTERNAL_STATUS_REGISTERED, SAM_INTERNAL_STATUS_STARTED, SAM_RECOVERY_POLICY_CMAP, and SAM_RECOVERY_POLICY_QUORUM.

◆ sam_stop()

cs_error_t sam_stop ( void )

Stop healthchecking.

Oposite of sam_start. You can call sam_start and sam_stop how many times you want.

Return values

CS_OK	in case no problem appeared
CS_ERR_BAD_HANDLE	healthchecking is not in running state (no sam_start was called)

Definition at line 635 of file sam.c.

References CS_ERR_BAD_HANDLE, CS_ERR_LIBRARY, CS_OK, nodeid, SAM_COMMAND_STOP, SAM_INTERNAL_STATUS_REGISTERED, SAM_INTERNAL_STATUS_STARTED, and SAM_RECOVERY_POLICY_CMAP.

Referenced by sam_finalize().

◆ sam_warn_signal_set()

cs_error_t sam_warn_signal_set ( int warn_signal )

Set warning signal to be sent.

Default signal is SIGTERM. You can use SIGKILL to emulate NOT sending warning signal and just send SIGKILL.

Return values

CS_OK	in case no problem appeared
CS_ERR_BAD_HANDLE	library was not initialized by sam_initialize or is finalized

Definition at line 741 of file sam.c.

References CS_ERR_BAD_HANDLE, CS_ERR_LIBRARY, CS_OK, nodeid, SAM_COMMAND_WARN_SIGNAL_SET, SAM_INTERNAL_STATUS_INITIALIZED, SAM_INTERNAL_STATUS_REGISTERED, SAM_INTERNAL_STATUS_STARTED, and warn_signal.

Typedefs

Enumerations

Functions

Typedef Documentation

◆ sam_hc_callback_t

Enumeration Type Documentation

◆ sam_recovery_policy_t

Function Documentation

◆ sam_data_getsize()

◆ sam_data_restore()

◆ sam_data_store()

◆ sam_finalize()

◆ sam_hc_callback_register()

◆ sam_hc_send()

◆ sam_initialize()

◆ sam_mark_failed()

◆ sam_register()

◆ sam_start()

◆ sam_stop()

◆ sam_warn_signal_set()