sam.c File Reference
`#include <config.h>`
`#include <limits.h>`
`#include <stdlib.h>`
`#include <string.h>`
`#include <unistd.h>`
`#include <sys/time.h>`
`#include <sys/types.h>`
`#include <sys/socket.h>`
`#include <errno.h>`
`#include <poll.h>`
`#include <corosync/corotypes.h>`
`#include <qb/qbipcc.h>`
`#include <corosync/corodefs.h>`
`#include <corosync/cmap.h>`
`#include <corosync/hdb.h>`
`#include <corosync/quorum.h>`
`#include <corosync/sam.h>`
`#include "util.h"`
`#include <stdio.h>`
`#include <sys/wait.h>`
`#include <signal.h>`
Include dependency graph for sam.c:

Go to the source code of this file.

## Macros

#define | SAM_CMAP_S_FAILED "failed"
#define | SAM_CMAP_S_REGISTERED "stopped"
#define | SAM_CMAP_S_STARTED "running"
#define | SAM_CMAP_S_Q_WAIT "waiting for quorum"
#define | SAM_RP_MASK_Q(pol) (pol & (~SAM_RECOVERY_POLICY_QUORUM))
#define | SAM_RP_MASK_C(pol) (pol & (~SAM_RECOVERY_POLICY_CMAP))
#define | SAM_RP_MASK(pol) (pol & (~(SAM_RECOVERY_POLICY_QUORUM | SAM_RECOVERY_POLICY_CMAP)))

## Enumerations

enum | sam_internal_status_t { SAM_INTERNAL_STATUS_NOT_INITIALIZED = 0 , SAM_INTERNAL_STATUS_INITIALIZED , SAM_INTERNAL_STATUS_REGISTERED , SAM_INTERNAL_STATUS_STARTED , SAM_INTERNAL_STATUS_FINALIZED }
enum | sam_command_t { SAM_COMMAND_START , SAM_COMMAND_STOP , SAM_COMMAND_HB , SAM_COMMAND_DATA_STORE , SAM_COMMAND_WARN_SIGNAL_SET , SAM_COMMAND_MARK_FAILED }
enum | sam_reply_t { SAM_REPLY_OK , SAM_REPLY_ERROR }
enum | sam_parent_action_t { SAM_PARENT_ACTION_ERROR , SAM_PARENT_ACTION_RECOVERY , SAM_PARENT_ACTION_QUIT , SAM_PARENT_ACTION_CONTINUE }
enum | sam_cmap_key_t { SAM_CMAP_KEY_RECOVERY , SAM_CMAP_KEY_HC_PERIOD , SAM_CMAP_KEY_LAST_HC , SAM_CMAP_KEY_STATE }

## Functions

cs_error_t | sam_initialize (int time_interval, sam_recovery_policy_t recovery_policy)
| Create a new SAM connection.
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_start (void)
| Start healthchecking.
cs_error_t | sam_stop (void)
| Stop healthchecking.
cs_error_t | sam_hc_send (void)
| Send healthcheck confirmation.
cs_error_t | sam_finalize (void)
| Close the SAM handle.
cs_error_t | sam_mark_failed (void)
| Marks child as failed.
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_callback_register (sam_hc_callback_t cb)
| Register healtcheck callback.

## Variables

const char * | __progname

## Macro Definition Documentation

## SAM_CMAP_S_FAILED

#define SAM_CMAP_S_FAILED "failed"

Definition at line 66 of file sam.c.

## SAM_CMAP_S_Q_WAIT

#define SAM_CMAP_S_Q_WAIT "waiting for quorum"

Definition at line 69 of file sam.c.

## SAM_CMAP_S_REGISTERED

#define SAM_CMAP_S_REGISTERED "stopped"

Definition at line 67 of file sam.c.

## SAM_CMAP_S_STARTED

#define SAM_CMAP_S_STARTED "running"

Definition at line 68 of file sam.c.

## SAM_RP_MASK

#define SAM_RP_MASK | ( |  | pol | ) | (pol & (~(SAM_RECOVERY_POLICY_QUORUM | SAM_RECOVERY_POLICY_CMAP)))

Definition at line 73 of file sam.c.

## SAM_RP_MASK_C

#define SAM_RP_MASK_C | ( |  | pol | ) | (pol & (~SAM_RECOVERY_POLICY_CMAP))

Definition at line 72 of file sam.c.

## SAM_RP_MASK_Q

#define SAM_RP_MASK_Q | ( |  | pol | ) | (pol & (~SAM_RECOVERY_POLICY_QUORUM))

Definition at line 71 of file sam.c.

## Enumeration Type Documentation

## sam_cmap_key_t

enum sam_cmap_key_t

Enumerator
SAM_CMAP_KEY_RECOVERY |
SAM_CMAP_KEY_HC_PERIOD |
SAM_CMAP_KEY_LAST_HC |
SAM_CMAP_KEY_STATE |

Definition at line 104 of file sam.c.

## sam_command_t

enum sam_command_t

Enumerator
SAM_COMMAND_START |
SAM_COMMAND_STOP |
SAM_COMMAND_HB |
SAM_COMMAND_DATA_STORE |
SAM_COMMAND_WARN_SIGNAL_SET |
SAM_COMMAND_MARK_FAILED |

Definition at line 83 of file sam.c.

## sam_internal_status_t

enum sam_internal_status_t

Enumerator
SAM_INTERNAL_STATUS_NOT_INITIALIZED |
SAM_INTERNAL_STATUS_INITIALIZED |
SAM_INTERNAL_STATUS_REGISTERED |
SAM_INTERNAL_STATUS_STARTED |
SAM_INTERNAL_STATUS_FINALIZED |

Definition at line 75 of file sam.c.

## sam_parent_action_t

enum sam_parent_action_t

Enumerator
SAM_PARENT_ACTION_ERROR |
SAM_PARENT_ACTION_RECOVERY |
SAM_PARENT_ACTION_QUIT |
SAM_PARENT_ACTION_CONTINUE |

Definition at line 97 of file sam.c.

## sam_reply_t

enum sam_reply_t

Enumerator
SAM_REPLY_OK |
SAM_REPLY_ERROR |

Definition at line 92 of file sam.c.

## 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.

## Variable Documentation

## __progname

const char* __progname

extern

## am_i_child

int am_i_child

Definition at line 120 of file sam.c.

## cb_registered

int cb_registered

Definition at line 125 of file sam.c.

## cb_rpipe_fd

int cb_rpipe_fd

Definition at line 124 of file sam.c.

## cb_thread

pthread_t cb_thread

Definition at line 123 of file sam.c.

## cb_wpipe_fd

int cb_wpipe_fd

Definition at line 124 of file sam.c.

## child_fd_in

int child_fd_in

Definition at line 117 of file sam.c.

## child_fd_out

int child_fd_out

Definition at line 116 of file sam.c.

## cmap_handle

cmap_handle_t cmap_handle

Definition at line 137 of file sam.c.

Referenced by corosync_log_config_read().

## cmap_pid_path

char cmap_pid_path[CMAP_KEYNAME_MAXLEN]

Definition at line 138 of file sam.c.

## hc_callback

sam_hc_callback_t hc_callback

Definition at line 122 of file sam.c.

## instance_id

unsigned int instance_id

Definition at line 115 of file sam.c.

Referenced by sam_register().

## internal_status

enum sam_internal_status_t internal_status

Definition at line 114 of file sam.c.

## lock

pthread_mutex_t lock

Definition at line 131 of file sam.c.

## quorate

uint32_t quorate

Definition at line 134 of file sam.c.

Referenced by quorum_getquorate().

## quorum_fd

int quorum_fd

Definition at line 135 of file sam.c.

## quorum_handle

quorum_handle_t quorum_handle

Definition at line 133 of file sam.c.

## recovery_policy

sam_recovery_policy_t recovery_policy

Definition at line 113 of file sam.c.

Referenced by sam_initialize().

## term_send

int term_send

Definition at line 118 of file sam.c.

## time_interval

int time_interval

Definition at line 112 of file sam.c.

Referenced by sam_initialize().

## user_data

void* user_data

Definition at line 127 of file sam.c.

Referenced by cmap_track_add(), icmap_track_add(), and stats_map_track_add().

## user_data_allocated

size_t user_data_allocated

Definition at line 129 of file sam.c.

## user_data_size

size_t user_data_size

Definition at line 128 of file sam.c.

## warn_signal

int warn_signal

Definition at line 119 of file sam.c.

Referenced by sam_warn_signal_set().