proxmox-mirrors/mirror_corosync
1
0
Fork 0
mirror of https://git.proxmox.com/git/mirror_corosync synced 2026-08-19 16:11:31 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Convert existing documentation to doxygen format.

Browse Source 
This patch modifies most of the existing comments in header files to be
in a format that doxygen can interpret.  This provides another
significant improvement to the web/pdf/etc generated documentation
without having to add new content.

Signed-off-by: Russell Bryant <russell@russellbryant.net>
Reviewed-by: Angus Salkeld <asalkeld@redhat.com>
This commit is contained in:
Russell Bryant 2011-03-11 20:50:41 -06:00 committed by Angus Salkeld
parent dddaeef21c
commit 5da4d5479a
28 changed files with 353 additions and 260 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
exec/main.h
View File

@ -32,6 +32,13 @@
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
* THE POSSIBILITY OF SUCH DAMAGE.
*/
/**
* @file
*
* @warning DO NOT USE SYMBOLS IN THIS FILE
*/
#ifndef MAIN_H_DEFINED
#define MAIN_H_DEFINED
@ -45,9 +52,6 @@
#include <corosync/engine/config.h>
#include <corosync/engine/coroapi.h>
/*
* DO NOT USE SYMBOLS IN THIS FILE
*/
extern unsigned long long *(*main_clm_get_by_nodeid) (unsigned int node_id);
extern void main_get_config_modules(struct config_iface_ver0 ***modules, int *num);

4
exec/mainconfig.h
View File

@ -40,7 +40,7 @@
#include <corosync/list.h>
#include <corosync/engine/coroapi.h>
/*
/**
* All service handlers in the AIS
*/
struct dynamic_service {
@ -51,7 +51,7 @@ struct dynamic_service {
};
#define MAX_DYNAMIC_SERVICES 128
/*
/**
* Structure describing cached uidgid item
*/
struct uidgid_item {

13
exec/service.h
View File

@ -36,17 +36,18 @@
#define COROSYNC_SERVICE_H_DEFINED
#include <corosync/hdb.h>
/*
* Link and initialize a service
*/
struct corosync_api_v1;
/**
* Link and initialize a service
*/
extern unsigned int corosync_service_link_and_init (
struct corosync_api_v1 *objdb,
const char *service_name,
unsigned int service_ver);
/*
/**
* Unlink and exit a service
*/
extern unsigned int corosync_service_unlink_and_exit (
@ -54,14 +55,14 @@ extern unsigned int corosync_service_unlink_and_exit (
const char *service_name,
unsigned int service_ver);
/*
/**
* Unlink and exit all corosync services
*/
extern void corosync_service_unlink_all (
struct corosync_api_v1 *api,
void (*unlink_all_complete) (void));
/*
/**
* Load all of the default services
*/
extern unsigned int corosync_service_defaults_link_and_init (

4
exec/tlist.h
View File

@ -243,7 +243,7 @@ static inline void timerlist_post_dispatch (struct timerlist *timerlist, timer_h
free (timer);
}
/*
/**
* returns the number of msec until the next timer will expire for use with poll
*/
static inline unsigned long long timerlist_msec_duration_to_expire (struct timerlist *timerlist)
@ -280,7 +280,7 @@ static inline unsigned long long timerlist_msec_duration_to_expire (struct timer
return (msec_duration_to_expire);
}
/*
/**
* Expires any timers that should be expired
*/
static inline void timerlist_expire (struct timerlist *timerlist)

2
exec/totemiba.h
View File

@ -40,7 +40,7 @@
#include <corosync/totem/totem.h>
/*
/**
* Create an instance
*/
extern int totemiba_initialize (

20
exec/totemmrp.h
View File

@ -32,16 +32,20 @@
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
* THE POSSIBILITY OF SUCH DAMAGE.
*/
/**
* @file
* Totem Single Ring Protocol
*
* depends on poll abstraction, POSIX, IPV4
*/
#ifndef TOTEMMRP_H_DEFINED
#define TOTEMMRP_H_DEFINED
#include <corosync/totem/totem.h>
/*
* Totem Single Ring Protocol
* depends on poll abstraction, POSIX, IPV4
*/
/*
/**
* Initialize the logger
*/
extern void totemmrp_log_printf_init (
@ -52,7 +56,7 @@ extern void totemmrp_log_printf_init (
int log_level_notice,
int log_level_debug);
/*
/**
* Initialize the group messaging interface
*/
extern int totemmrp_initialize (
@ -74,7 +78,7 @@ extern int totemmrp_initialize (
extern void totemmrp_finalize (void);
/*
/**
* Multicast a message
*/
extern int totemmrp_mcast (
@ -82,7 +86,7 @@ extern int totemmrp_mcast (
unsigned int iov_len,
int priority);
/*
/**
* Return number of available messages that can be queued
*/
extern int totemmrp_avail (void);

14
exec/totemnet.h
View File

@ -32,6 +32,14 @@
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
* THE POSSIBILITY OF SUCH DAMAGE.
*/
/**
* @file
* Totem Network interface - also does encryption/decryption
*
* depends on poll abstraction, POSIX, IPV4
*/
#ifndef TOTEMNET_H_DEFINED
#define TOTEMNET_H_DEFINED
@ -42,12 +50,8 @@
#define TOTEMNET_NOFLUSH 0
#define TOTEMNET_FLUSH 1
/*
* Totem Network interface - also does encryption/decryption
* depends on poll abstraction, POSIX, IPV4
*/
/*
/**
* Create an instance
*/
extern int totemnet_initialize (

15
exec/totemrrp.h
View File

@ -32,6 +32,14 @@
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
* THE POSSIBILITY OF SUCH DAMAGE.
*/
/**
* @file
* Totem Network interface - also does encryption/decryption
*
* depends on poll abstraction, POSIX, IPV4
*/
#ifndef TOTEMRRP_H_DEFINED
#define TOTEMRRP_H_DEFINED
@ -43,12 +51,7 @@
#define TOTEMRRP_NOFLUSH 0
#define TOTEMRRP_FLUSH 1
/*
* Totem Network interface - also does encryption/decryption
* depends on poll abstraction, POSIX, IPV4
*/
/*
/**
* Create an instance
*/
extern int totemrrp_initialize (

19
exec/totemsrp.h
View File

@ -32,18 +32,21 @@
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
* THE POSSIBILITY OF SUCH DAMAGE.
*/
/**
* @file
* Totem Single Ring Protocol
*
* depends on poll abstraction, POSIX, IPV4
*/
#ifndef TOTEMSRP_H_DEFINED
#define TOTEMSRP_H_DEFINED
#include <corosync/totem/totem.h>
#include <corosync/totem/coropoll.h>
/*
* Totem Single Ring Protocol
* depends on poll abstraction, POSIX, IPV4
*/
/*
/**
* Create a protocol instance
*/
int totemsrp_initialize (
@ -66,7 +69,7 @@ int totemsrp_initialize (
void totemsrp_finalize (void *srp_context);
/*
/**
* Multicast a message
*/
int totemsrp_mcast (
@ -75,7 +78,7 @@ int totemsrp_mcast (
unsigned int iov_len,
int priority);
/*
/**
* Return number of available messages that can be queued
*/
int totemsrp_avail (void *srp_context);

2
exec/totemudp.h
View File

@ -41,7 +41,7 @@
#include <corosync/totem/totem.h>
/*
/**
* Create an instance
*/
extern int totemudp_initialize (

2
exec/totemudpu.h
View File

@ -41,7 +41,7 @@
#include <corosync/totem/totem.h>
/*
/**
* Create an instance
*/
extern int totemudpu_initialize (

4
exec/util.h
View File

@ -38,7 +38,7 @@
#include <sys/time.h>
#include <corosync/corotypes.h>
/*
/**
* Get the time of day and convert to nanoseconds
*/
extern cs_time_t clust_time_now(void);
@ -86,7 +86,7 @@ static inline cs_error_t hdb_error_to_cs (int res) \
} \
}
/*
/**
* Compare two names. returns non-zero on match.
*/
extern int name_match(cs_name_t *name1, cs_name_t *name2);

7
exec/vsf.h
View File

@ -37,7 +37,7 @@
struct corosync_api_v1;
struct corosync_vsf_iface_ver0 {
/*
/**
* Executes a callback whenever component changes
*/
int (*init) (
@ -48,8 +48,9 @@ struct corosync_vsf_iface_ver0 {
int primary_designated,
struct memb_ring_id *ring_id));
/*
* Returns 1 if we are primary component, 0 if not
/**
* @retval 1 if we are primary component
* @retval 0 if not primary component
*/
int (*primary) (void);
};

24
include/corosync/cfg.h
View File

@ -82,14 +82,23 @@ typedef enum {
COROSYNC_CFG_STATETYPE_PRESENCE = 4
} corosync_cfg_state_type_t;
/* Shutdown types.
REQUEST is the normal shutdown. other daemons will be consulted
REGARDLESS will tell other daemons but ignore their opinions
IMMEDIATE will shut down straight away (but still tell other nodes)
*/
/**
* Shutdown types.
*/
typedef enum {
/**
* REQUEST is the normal shutdown.
* Other daemons will be consulted.
*/
COROSYNC_CFG_SHUTDOWN_FLAG_REQUEST = 0,
/**
* REGARDLESS will tell other daemons but ignore their opinions.
*/
COROSYNC_CFG_SHUTDOWN_FLAG_REGARDLESS = 1,
/**
* IMMEDIATE will shut down straight away
* (but still tell other nodes).
*/
COROSYNC_CFG_SHUTDOWN_FLAG_IMMEDIATE = 2,
} corosync_cfg_shutdown_flags_t;
@ -122,8 +131,9 @@ typedef struct {
corosync_cfg_shutdown_callback_t corosync_cfg_shutdown_callback;
} corosync_cfg_callbacks_t;
/*
/**
* A node address. This is a complete sockaddr_in[6]
*
* To explain:
* If you cast cna_address to a 'struct sockaddr', the sa_family field
* will be AF_INET or AF_INET6. Armed with that knowledge you can then
@ -133,7 +143,7 @@ typedef struct {
*/
typedef struct
{
int address_length; /* FIXME: set but never used */
int address_length; /**< @todo FIXME: set but never used */
char address[sizeof(struct sockaddr_in6)];
} corosync_cfg_node_address_t;

39
include/corosync/confdb.h
View File

@ -118,21 +118,21 @@ typedef struct {
/** @} */
/*
/**
* Create a new confdb connection
*/
cs_error_t confdb_initialize (
confdb_handle_t *handle,
confdb_callbacks_t *callbacks);
/*
/**
* Close the confdb handle
*/
cs_error_t confdb_finalize (
confdb_handle_t handle);
/*
/**
* Write back the configuration
*/
cs_error_t confdb_write (
@ -140,7 +140,7 @@ cs_error_t confdb_write (
char *error_text,
size_t errbuf_len);
/*
/**
* Reload the configuration
*/
cs_error_t confdb_reload (
@ -149,22 +149,23 @@ cs_error_t confdb_reload (
char *error_text,
size_t errbuf_len);
/*
* Get a file descriptor on which to poll. confdb_handle_t is NOT a
* file descriptor and may not be used directly.
/**
* Get a file descriptor on which to poll.
*
* confdb_handle_t is NOT a file descriptor and may not be used directly.
*/
cs_error_t confdb_fd_get (
confdb_handle_t handle,
int *fd);
/*
/**
* Dispatch configuration changes
*/
cs_error_t confdb_dispatch (
confdb_handle_t handle,
cs_dispatch_flags_t dispatch_types);
/*
/**
* Change notification
*/
cs_error_t confdb_track_changes (
@ -175,7 +176,7 @@ cs_error_t confdb_track_changes (
cs_error_t confdb_stop_track_changes (
confdb_handle_t handle);
/*
/**
* Manipulate objects
*/
cs_error_t confdb_object_create (
@ -200,7 +201,7 @@ cs_error_t confdb_object_name_get (
char *object_name,
size_t *object_name_len);
/*
/**
* Manipulate keys
*/
cs_error_t confdb_key_create (
@ -227,7 +228,7 @@ cs_error_t confdb_key_delete (
const void *value,
size_t value_len);
/*
/**
* Key queries
*/
cs_error_t confdb_key_get (
@ -270,10 +271,12 @@ cs_error_t confdb_key_decrement (
size_t key_name_len,
unsigned int *value);
/*
/**
* Object queries
*
* "find" loops through all objects of a given name and is also
* a quick way of finding a specific object,
*
* "iter" returns each object in sequence.
*/
cs_error_t confdb_object_find_start (
@ -306,7 +309,7 @@ cs_error_t confdb_object_iter_destroy(
confdb_handle_t handle,
hdb_handle_t parent_object_handle);
/*
/**
* Key iterator
*/
cs_error_t confdb_key_iter_start (
@ -329,14 +332,16 @@ cs_error_t confdb_key_iter_typed (
size_t *value_len,
confdb_value_types_t *type);
/*
* Get/set context variable
/**
* Get context variable
*/
cs_error_t confdb_context_get (
confdb_handle_t handle,
const void **context);
/**
* Set context variable
*/
cs_error_t confdb_context_set (
confdb_handle_t handle,
const void *context);

53
include/corosync/cpg.h
View File

@ -52,15 +52,15 @@ typedef uint64_t cpg_handle_t;
typedef uint64_t cpg_iteration_handle_t;
typedef enum {
CPG_TYPE_UNORDERED, /* not implemented */
CPG_TYPE_FIFO, /* same as agreed */
CPG_TYPE_UNORDERED, /**< not implemented */
CPG_TYPE_FIFO, /**< same as agreed */
CPG_TYPE_AGREED,
CPG_TYPE_SAFE /* not implemented */
CPG_TYPE_SAFE /**< not implemented */
} cpg_guarantee_t;
typedef enum {
CPG_FLOW_CONTROL_DISABLED, /* flow control is disabled - new messages may be sent */
CPG_FLOW_CONTROL_ENABLED /* flow control is enabled - new messages should not be sent */
CPG_FLOW_CONTROL_DISABLED, /**< flow control is disabled - new messages may be sent */
CPG_FLOW_CONTROL_ENABLED /**< flow control is enabled - new messages should not be sent */
} cpg_flow_control_state_t;
@ -112,7 +112,7 @@ typedef void (*cpg_deliver_fn_t) (
const struct cpg_name *group_name,
uint32_t nodeid,
uint32_t pid,
/*
/**
* Unlike many "msg" pointers, this one is deliberately *not*
* declared const in order to permit in-place endian conversion.
*/
@ -154,14 +154,14 @@ typedef struct {
/** @} */
/*
/**
* Create a new cpg connection
*/
cs_error_t cpg_initialize (
cpg_handle_t *handle,
cpg_callbacks_t *callbacks);
/*
/**
* Create a new cpg connection, initialize with model
*/
cs_error_t cpg_model_initialize (
@ -170,41 +170,46 @@ cs_error_t cpg_model_initialize (
cpg_model_data_t *model_data,
void *context);
/*
/**
* Close the cpg handle
*/
cs_error_t cpg_finalize (
cpg_handle_t handle);
/*
* Get a file descriptor on which to poll. cpg_handle_t is NOT a
* file descriptor and may not be used directly.
/**
* Get a file descriptor on which to poll.
*
* cpg_handle_t is NOT a file descriptor and may not be used directly.
*/
cs_error_t cpg_fd_get (
cpg_handle_t handle,
int *fd);
/*
* Get and set contexts for a CPG handle
/**
* Get contexts for a CPG handle
*/
cs_error_t cpg_context_get (
cpg_handle_t handle,
void **context);
/**
* Set contexts for a CPG handle
*/
cs_error_t cpg_context_set (
cpg_handle_t handle,
void *context);
/*
/**
* Dispatch messages and configuration changes
*/
cs_error_t cpg_dispatch (
cpg_handle_t handle,
cs_dispatch_flags_t dispatch_types);
/*
/**
* Join one or more groups.
*
* messages multicasted with cpg_mcast_joined will be sent to every
* group that has been joined on handle handle. Any message multicasted
* to a group that has been previously joined will be delivered in cpg_dispatch
@ -213,17 +218,21 @@ cs_error_t cpg_join (
cpg_handle_t handle,
const struct cpg_name *group);
/*
/**
* Leave one or more groups
*/
cs_error_t cpg_leave (
cpg_handle_t handle,
const struct cpg_name *group);
/*
/**
* Multicast to groups joined with cpg_join.
* The iovec described by iovec will be multicasted to all groups joined with
* the cpg_join interface for handle.
*
* @param handle
* @param guarantee
* @param iovec This iovec will be multicasted to all groups joined with
* the cpg_join interface for handle.
* @param iov_len
*/
cs_error_t cpg_mcast_joined (
cpg_handle_t handle,
@ -231,7 +240,7 @@ cs_error_t cpg_mcast_joined (
const struct iovec *iovec,
unsigned int iov_len);
/*
/**
* Get membership information from cpg
*/
cs_error_t cpg_membership_get (
@ -263,7 +272,7 @@ cs_error_t cpg_zcb_mcast_joined (
void *msg,
size_t msg_len);
/*
/**
* Iteration
*/
cs_error_t cpg_iteration_initialize(

40
include/corosync/evs.h
View File

@ -92,47 +92,52 @@ typedef struct {
/** @} */
/*
/**
* Create a new evs connection
*/
cs_error_t evs_initialize (
evs_handle_t *handle,
evs_callbacks_t *callbacks);
/*
/**
* Close the evs handle
*/
cs_error_t evs_finalize (
evs_handle_t handle);
/*
* Get a file descriptor on which to poll. evs_handle_t is NOT a
* file descriptor and may not be used directly.
/**
* Get a file descriptor on which to poll.
*
* evs_handle_t is NOT a file descriptor and may not be used directly.
*/
cs_error_t evs_fd_get (
evs_handle_t handle,
int *fd);
/*
* Get and set contexts for a EVS handle
/**
* Get contexts for a EVS handle
*/
cs_error_t evs_context_get (
evs_handle_t handle,
void **context);
/**
* Set contexts for a EVS handle
*/
cs_error_t evs_context_set (
evs_handle_t handle,
void *context);
/*
/**
* Dispatch messages and configuration changes
*/
cs_error_t evs_dispatch (
evs_handle_t handle,
cs_dispatch_flags_t dispatch_types);
/*
/**
* Join one or more groups.
*
* messages multicasted with evs_mcast_joined will be sent to every
* group that has been joined on handle handle. Any message multicasted
* to a group that has been previously joined will be delivered in evs_dispatch
@ -142,7 +147,7 @@ cs_error_t evs_join (
const struct evs_group *groups,
size_t group_cnt);
/*
/**
* Leave one or more groups
*/
cs_error_t evs_leave (
@ -150,10 +155,14 @@ cs_error_t evs_leave (
const struct evs_group *groups,
size_t group_cnt);
/*
/**
* Multicast to groups joined with evs_join.
* The iovec described by iovec will be multicasted to all groups joined with
* the evs_join interface for handle.
*
* @param handle
* @param guarantee
* @param iovec This iovec will be multicasted to all groups joined with
* the evs_join interface for handle.
* @param iov_len
*/
cs_error_t evs_mcast_joined (
evs_handle_t handle,
@ -161,8 +170,9 @@ cs_error_t evs_mcast_joined (
const struct iovec *iovec,
unsigned int iov_len);
/*
/**
* Multicast to specified groups.
*
* Messages will be multicast to groups specified in the api call and not those
* that have been joined (unless they are in the groups parameter).
*/
@ -174,7 +184,7 @@ cs_error_t evs_mcast_groups (
const struct iovec *iovec,
unsigned int iov_len);
/*
/**
* Get membership information from evs
*/
cs_error_t evs_membership_get (

4
include/corosync/ipc_cpg.h
View File

@ -222,7 +222,9 @@ struct res_lib_cpg_mcast {
coroipc_response_header_t header __attribute__((aligned(8)));
};
/* Message from another node */
/**
* Message from another node
*/
struct res_lib_cpg_deliver_callback {
coroipc_response_header_t header __attribute__((aligned(8)));
mar_cpg_name_t group_name __attribute__((aligned(8)));

13
include/corosync/lcr/lcr_ckpt.h
View File

@ -31,25 +31,26 @@
#ifndef LCR_CKPT_H_DEFINED
#define LCR_CKPT_H_DEFINED
/*
/**
* Write data of length data_len into the section name for ckpt_handle
*/
int lcr_ckpt_section_write (void *ckpt_handle, const char *name,
const void *data, size_t data_len);
/*
* Read the section name into data with data len. Returned in data_len is the
* actual data read from ckpt_handle.
/**
* Read the section name into data with data len.
*
* @retval Returned in data_len is the actual data read from ckpt_handle.
*/
int lcr_ckpt_section_read (void *ckpt_handle, const char *name,
void *data, size_t *data_len);
/*
/**
* Initialize the section iterator to the first section
*/
int lcr_ckpt_section_iterator_first (void *ckpt_handle);
/*
/**
* Get the current section, return it in name, and advance to next section
*/
int lcr_ckpt_section_iterator_next (void *ckpt_handle, char **name);

26
include/corosync/lcr/lcr_comp.h
View File

@ -31,27 +31,27 @@
#ifndef LCR_COMP_H_DEFINED
#define LCR_COMP_H_DEFINED
/*
/**
* LCR Interface
*/
struct lcr_iface {
const char *name; /* Name of the interface */
int version; /* Version of this interface */
int *versions_replace; /* Versions that this interface can replace */
int versions_replace_count; /* Count of entries in version_replace */
char **dependencies; /* Dependent interfaces */
size_t dependency_count; /* Count of entires in dependencies */
int (*constructor) (void *context); /* Constructor for this interface */
void (*destructor) (void *context); /* Constructor for this interface */
void **interfaces; /* List of functions in interface */
const char *name; /**< Name of the interface */
int version; /**< Version of this interface */
int *versions_replace; /**< Versions that this interface can replace */
int versions_replace_count; /**< Count of entries in version_replace */
char **dependencies; /**< Dependent interfaces */
size_t dependency_count; /**< Count of entires in dependencies */
int (*constructor) (void *context); /**< Constructor for this interface */
void (*destructor) (void *context); /**< Constructor for this interface */
void **interfaces; /**< List of functions in interface */
};
/*
/**
* LCR Component
*/
struct lcr_comp {
struct lcr_iface *ifaces; /* List of interfaces in this component */
size_t iface_count; /* size of ifaces list */
struct lcr_iface *ifaces; /**< List of interfaces in this component */
size_t iface_count; /**< size of ifaces list */
};
extern void lcr_component_register (struct lcr_comp *comp);

7
include/corosync/list.h
View File

@ -31,10 +31,15 @@
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
* THE POSSIBILITY OF SUCH DAMAGE.
*/
/*
/**
* @file
* Linked list API
*
* This implementation uses the same API as the linux kernel to
* help us kernel developers easily use the list primatives
*/
#ifndef LIST_H_DEFINED
#define LIST_H_DEFINED

11
include/corosync/pload.h
View File

@ -74,22 +74,23 @@ typedef struct {
/** @} */
/*
/**
* Create a new pload connection
*/
pload_error_t pload_initialize (
pload_handle_t *handle,
pload_callbacks_t *callbacks);
/*
/**
* Close the pload handle
*/
pload_error_t pload_finalize (
pload_handle_t handle);
/*
* Get a file descriptor on which to poll. pload_handle_t is NOT a
* file descriptor and may not be used directly.
/**
* Get a file descriptor on which to poll.
*
* @note pload_handle_t is NOT a file descriptor and may not be used directly.
*/
pload_error_t pload_fd_get (
pload_handle_t handle,

19
include/corosync/quorum.h
View File

@ -60,29 +60,30 @@ typedef struct {
} quorum_callbacks_t;
/*
/**
* Create a new quorum connection
*/
cs_error_t quorum_initialize (
quorum_handle_t *handle,
quorum_callbacks_t *callbacks);
/*
/**
* Close the quorum handle
*/
cs_error_t quorum_finalize (
quorum_handle_t handle);
/*
* Get a file descriptor on which to poll. quorum_handle_t is NOT a
* file descriptor and may not be used directly.
/**
* Get a file descriptor on which to poll.
*
* @note quorum_handle_t is NOT a file descriptor and may not be used directly.
*/
cs_error_t quorum_fd_get (
quorum_handle_t handle,
int *fd);
/*
/**
* Dispatch messages and configuration changes
*/
cs_error_t quorum_dispatch (
@ -90,14 +91,16 @@ cs_error_t quorum_dispatch (
cs_dispatch_flags_t dispatch_types);
/*
/**
* Get quorum information.
*/
cs_error_t quorum_getquorate (
quorum_handle_t handle,
int *quorate);
/* Track node and quorum changes */
/**
* Track node and quorum changes
*/
cs_error_t quorum_trackstart (
quorum_handle_t handle,
unsigned int flags );

196
include/corosync/sam.h
View File

@ -49,173 +49,193 @@ typedef enum {
SAM_RECOVERY_POLICY_CONFDB = 0x10,
} sam_recovery_policy_t;
/*
/**
* Callback definition for event driven checking
*/
typedef int (*sam_hc_callback_t)(void);
/*
* Create a new SAM connection. This function must be called before any other.
/**
* 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.
*
* @param time_interval Time interval in miliseconds 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)
* 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)
* @param 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
* - 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
* timeout application will be killed and new instance will be started.
* SAM_RECOVERY_POLICY_QUIT will just stop application
*
* @retval CS_OK in case no problem appeared
* @retval CS_ERR_BAD_HANDLE in case user is trying to initialize initialized instance
* @retval CS_ERR_INVALID_PARAM in case recovery_policy had bad value
*/
cs_error_t sam_initialize (
int time_interval,
sam_recovery_policy_t recovery_policy);
/*
* Close the SAM handle. This function should be called as late as possible
/**
* 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
* - CS_OK in case no problem appeared
* - CS_ERR_BAD_HANDLE library was not initialized by #sam_initialize
* @retval CS_OK in case no problem appeared
* @retval CS_ERR_BAD_HANDLE library was not initialized by #sam_initialize
*/
cs_error_t sam_finalize (void);
/*
* Start healthchecking. From this time, you should call every time_interval
/**
* Start healthchecking.
*
* From this time, you should call every time_interval
* sam_hc_send, otherwise, recovery action will be taken.
* @return
* - CS_OK in case no problem appeared
* - CS_ERR_BAD_HANDLE component was not registered by #sam_register
*
* @retval CS_OK in case no problem appeared
* @retval CS_ERR_BAD_HANDLE component was not registered by #sam_register
*/
cs_error_t sam_start (void);
/*
* Stop healthchecking. Oposite of #sam_start. You can call sam_start and
* sam_stop how many times you want.
/**
* Stop healthchecking.
*
* @return
* - CS_OK in case no problem appeared
* - CS_ERR_BAD_HANDLE healthchecking is not in running state (no sam_start
* was called)
* Oposite of #sam_start. You can call sam_start and sam_stop how many
* times you want.
*
* @retval CS_OK in case no problem appeared
* @retval CS_ERR_BAD_HANDLE healthchecking is not in running state (no sam_start
* was called)
*/
cs_error_t sam_stop (void);
/*
* Set warning signal to be send. Default signal is SIGTERM. You can
* use SIGKILL to emulate NOT sending warning signal and just send
* SIGKILL.
/**
* Set warning signal to be send.
*
* @return
* - CS_OK in case no problem appeared
* - CS_ERR_BAD_HANDLE library was not initialized by #sam_initialize or
* is finalized
* Default signal is SIGTERM. You can use SIGKILL to emulate NOT sending
* warning signal and just send SIGKILL.
*
* @retval CS_OK in case no problem appeared
* @retval CS_ERR_BAD_HANDLE library was not initialized by #sam_initialize or
* is finalized
*/
cs_error_t sam_warn_signal_set (int warn_signal);
/*
* Register application. This is one of most crucial function. In case, your
/**
* 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.
*
* @param 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
* - 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
* 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).
*
* @retval CS_OK in case no problem appeared
* @retval CS_ERR_BAD_HANDLE in case, you call this function twice, or before sam_init
* @retval CS_ERR_LIBRARY internal library call failed. This can be one of pipe or fork
* creation. You can get more information from errno
*/
cs_error_t sam_register (
unsigned int *instance_id);
/*
* Send healthcheck confirmation. This should be called after #sam_start
/**
* Send healthcheck confirmation.
*
* - 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)
* This should be called after #sam_start
*
* @retval CS_OK in case no problem appeared
* @retval CS_ERR_BAD_HANDLE healthchecking is not in running state (no sam_start was
* called, or called after sam_stop/sam_finalize)
*/
cs_error_t sam_hc_send (void);
/*
* Register healtcheck callback. After you will call this function, and set
/**
* 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.
*
* @param cb Pointer to healtcheck function, or NULL to switch back to application driven hc
* @return
* - 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.
*
* @retval CS_OK in case no problem appeared
* @retval CS_ERR_BAD_HANDLE in case, you call this function before sam_init or after sam_start
* @retval CS_ERR_LIBRARY internal library call failed. This can be one of pipe or pthread
* creation.
*/
cs_error_t sam_hc_callback_register (sam_hc_callback_t cb);
/*
/**
* Return size of stored data.
*
* @param size Pointer to variable, where stored data size is returned. If
* nothing or NULL is stored, then 0 is returned.
* @return
* - 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
* nothing or NULL is stored, then 0 is returned.
*
* @retval CS_OK in case no problem appeared
* @retval CS_ERR_BAD_HANDLE in case you call this function before sam_init or after
* sam_finalize
* @retval CS_ERR_INVALID_PARAM if size parameter is NULL
*/
cs_error_t sam_data_getsize (size_t *size);
/*
/**
* Return stored data.
*
* @param data Pointer to place, where to store data
* @param size Allocated size of data
* @return
* - 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
*
* @retval CS_OK if no problem appeared
* @retval CS_ERR_BAD_HANDLE if you call this function before sam_init or after sam_finalize
* @retval CS_ERR_INVALID_PARAM if data is NULL or size is less then currently saved user data length
*/
cs_error_t sam_data_restore (
void *data,
size_t size);
/*
* Store user data. Such stored data survives restart of child.
/**
* Store user data.
*
* Such stored data survives restart of child.
*
* @param data Data to store. You can use NULL to delete data
* @param size Size of data to store.
* @return
* - 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
* sucesfull
* - CS_ERR_LIBRARY if some internal error appeared (communication with parent
* process)
*
* @retval CS_OK in case no problem appeared
* @retval CS_ERR_BAD_HANDLE if you call this function before sam_init or
* after sam_finalize
* @retval CS_ERR_NO_MEMORY if data is too large and malloc/realloc was not
* sucesfull
* @retval CS_ERR_LIBRARY if some internal error appeared (communication with parent
* process)
*/
cs_error_t sam_data_store (
const void *data,
size_t size);
/*
* Marks child as failed. This can be called only with SAM_RECOVERY_POLICY_CONFDB flag set and
/**
* Marks child as failed.
*
* This can be called only with SAM_RECOVERY_POLICY_CONFDB flag set and
* makes sense only for SAM_RECOVERY_POLICY_RESTART. This will kill child without sending warn
* signal. Confdb state key will be set to failed.
*
* - 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 has SAM_RECOVERY_POLICY_CONFDB flag set
* - CS_ERR_LIBRARY if some internal error appeared (communication with parent
* process)
* @retval CS_OK in case no problem appeared
* @retval CS_ERR_BAD_HANDLE library was not initialized or was already finalized
* @retval CS_ERR_INVALID_PARAM recovery policy doesn't has SAM_RECOVERY_POLICY_CONFDB flag set
* @retval CS_ERR_LIBRARY if some internal error appeared (communication with parent
* process)
*/
cs_error_t sam_mark_failed (void);

7
include/corosync/sq.h
View File

@ -53,15 +53,16 @@ struct sq {
* Compare a unsigned rollover-safe value to an unsigned rollover-safe value
*/
/*
/**
* ADJUST_ROLLOVER_POINT is the value used to determine when a window should be
* used to calculate a less-then or less-then-equal comparison.
*
*/
#define ADJUST_ROLLOVER_POINT 0x80000000
/**
* ADJUST_ROLLOVER_VALUE is the value by which both values in a comparison are
* adjusted if either value in a comparison is greater then
* ADJUST_ROLLOVER_POINT.
*/
#define ADJUST_ROLLOVER_POINT 0x80000000
#define ADJUST_ROLLOVER_VALUE 0x10000
static inline int sq_lt_compare (unsigned int a, unsigned int b) {

3
include/corosync/totem/totem.h
View File

@ -52,7 +52,7 @@
#define SEND_THREADS_MAX 16
#define INTERFACE_MAX 2
/*
/**
* Maximum number of continuous gather states
*/
#define MAX_NO_CONT_GATHER 3
@ -65,7 +65,6 @@ struct totem_interface {
uint16_t ttl;
int member_count;
struct totem_ip_address member_list[PROCESSOR_COUNT_MAX];
};
struct totem_logging_configuration {

16
include/corosync/totem/totempg.h
View File

@ -33,6 +33,13 @@
* THE POSSIBILITY OF SUCH DAMAGE.
*/
/**
* @file
* Totem Single Ring Protocol
*
* depends on poll abstraction, POSIX, IPV4
*/
#ifndef TOTEMPG_H_DEFINED
#define TOTEMPG_H_DEFINED
@ -53,12 +60,7 @@ struct totempg_group {
#define TOTEMPG_AGREED 0
#define TOTEMPG_SAFE 1
/*
* Totem Single Ring Protocol
* depends on poll abstraction, POSIX, IPV4
*/
/*
/**
* Initialize the totem process groups abstraction
*/
extern int totempg_initialize (
@ -76,7 +78,7 @@ extern int totempg_callback_token_create (void **handle_out,
extern void totempg_callback_token_destroy (void *handle);
/*
/**
* Initialize a groups instance
*/
extern int totempg_groups_initialize (

39
include/corosync/votequorum.h
View File

@ -102,36 +102,38 @@ typedef struct {
} votequorum_callbacks_t;
/*
/**
* Create a new quorum connection
*/
cs_error_t votequorum_initialize (
votequorum_handle_t *handle,
votequorum_callbacks_t *callbacks);
/*
/**
* Close the quorum handle
*/
cs_error_t votequorum_finalize (
votequorum_handle_t handle);
/*
/**
* Dispatch messages and configuration changes
*/
cs_error_t votequorum_dispatch (
votequorum_handle_t handle,
cs_dispatch_flags_t dispatch_types);
/*
* Get a file descriptor on which to poll. votequorum_handle_t is NOT a
* file descriptor and may not be used directly.
/**
* Get a file descriptor on which to poll.
*
* @note votequorum_handle_t is NOT a file descriptor and may not be
* used directly.
*/
cs_error_t votequorum_fd_get (
votequorum_handle_t handle,
int *fd);
/*
/**
* Get quorum information.
*/
cs_error_t votequorum_getinfo (
@ -139,14 +141,14 @@ cs_error_t votequorum_getinfo (
unsigned int nodeid,
struct votequorum_info *info);
/*
/**
* set expected_votes
*/
cs_error_t votequorum_setexpected (
votequorum_handle_t handle,
unsigned int expected_votes);
/*
/**
* set votes for a node
*/
cs_error_t votequorum_setvotes (
@ -154,8 +156,9 @@ cs_error_t votequorum_setvotes (
unsigned int nodeid,
unsigned int votes);
/*
/**
* Register a quorum device
*
* it will be DEAD until polled
*/
cs_error_t votequorum_qdisk_register (
@ -163,33 +166,35 @@ cs_error_t votequorum_qdisk_register (
const char *name,
unsigned int votes);
/*
/**
* Unregister a quorum device
*/
cs_error_t votequorum_qdisk_unregister (
votequorum_handle_t handle);
/*
/**
* Poll a quorum device
*/
cs_error_t votequorum_qdisk_poll (
votequorum_handle_t handle,
unsigned int state);
/*
/**
* Get quorum device information
*/
cs_error_t votequorum_qdisk_getinfo (
votequorum_handle_t handle,
struct votequorum_qdisk_info *info);
/*
/**
* Set the "hasstate" bit for this node
*/
cs_error_t votequorum_setstate (
votequorum_handle_t handle);
/* Track node and quorum changes */
/**
* Track node and quorum changes
*/
cs_error_t votequorum_trackstart (
votequorum_handle_t handle,
uint64_t context,
@ -198,13 +203,13 @@ cs_error_t votequorum_trackstart (
cs_error_t votequorum_trackstop (
votequorum_handle_t handle);
/*
/**
* Set our LEAVING flag. we should exit soon after this
*/
cs_error_t votequorum_leaving (
votequorum_handle_t handle);
/*
/**
* Save and retrieve private data/context
*/
cs_error_t votequorum_context_get (