[Openais] [corosync] cpg_model_initialize - Man page
Steven Dake
sdake at redhat.com
Mon Apr 19 11:24:09 PDT 2010
good for merge although i think this was inyour final
cpg_model_initialize patch
regards
-steve
On Wed, 2010-04-07 at 15:02 +0200, Jan Friesse wrote:
> SUBJ
>
> Regards,
> Honza
> plain text document attachment
> (2010-04-07-cpg_model_initialize-manpage.patch)
> commit ffc84d55cb7a6b207da6e131f0875328f76f631d
> Author: Jan Friesse <jfriesse at redhat.com>
> Date: Wed Apr 7 15:00:19 2010 +0200
>
> cpg_model_initialize man page
>
> diff --git a/trunk/man/Makefile.am b/trunk/man/Makefile.am
> index da01c2e..fe8f71b 100644
> --- a/trunk/man/Makefile.am
> +++ b/trunk/man/Makefile.am
> @@ -71,6 +71,7 @@ dist_man_MANS = \
> cpg_leave.3 \
> cpg_local_get.3 \
> cpg_mcast_joined.3 \
> + cpg_model_initialize.3 \
> cpg_zcb_mcast_joined.3 \
> cpg_zcb_alloc.3 \
> cpg_zcb_free.3 \
> diff --git a/trunk/man/cpg_initialize.3 b/trunk/man/cpg_initialize.3
> index ce6e25a..6d4bc51 100644
> --- a/trunk/man/cpg_initialize.3
> +++ b/trunk/man/cpg_initialize.3
> @@ -41,7 +41,10 @@ cpg_initialize \- Create a new connection to the CPG service
> .SH DESCRIPTION
> The
> .B cpg_initialize
> -function is used to initialize a connection to the closed process groups API.
> +function is used to initialize a connection to the closed process groups API. This function is deprecated
> +and
> +.B cpg_model_initialize
> +should be used in newly written code.
> .PP
> Each application may have several connections to the CPG API. Each application
> uses the
> @@ -167,5 +170,6 @@ The errors are undocumented.
> .BR cpg_context_get (3)
> .BR cpg_context_set (3)
> .BR cpg_local_get (3)
> +.BR cpg_model_initialize (3)
>
> .PP
> diff --git a/trunk/man/cpg_model_initialize.3 b/trunk/man/cpg_model_initialize.3
> new file mode 100644
> index 0000000..8ecf810
> --- /dev/null
> +++ b/trunk/man/cpg_model_initialize.3
> @@ -0,0 +1,227 @@
> +.\"/*
> +.\" * Copyright (c) 2010 Red Hat, Inc.
> +.\" *
> +.\" * All rights reserved.
> +.\" *
> +.\" * Author: Jan Friesse <jfriesse at redhat.com>
> +.\" * Author: Christine Caulfield <ccaulfie at redhat.com>
> +.\" *
> +.\" * This software licensed under BSD license, the text of which follows:
> +.\" *
> +.\" * Redistribution and use in source and binary forms, with or without
> +.\" * modification, are permitted provided that the following conditions are met:
> +.\" *
> +.\" * - Redistributions of source code must retain the above copyright notice,
> +.\" * this list of conditions and the following disclaimer.
> +.\" * - Redistributions in binary form must reproduce the above copyright notice,
> +.\" * this list of conditions and the following disclaimer in the documentation
> +.\" * and/or other materials provided with the distribution.
> +.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
> +.\" * contributors may be used to endorse or promote products derived from this
> +.\" * software without specific prior written permission.
> +.\" *
> +.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
> +.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
> +.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
> +.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
> +.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
> +.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
> +.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
> +.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
> +.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
> +.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
> +.\" * THE POSSIBILITY OF SUCH DAMAGE.
> +.\" */
> +.TH CPG_MODEL_INITIALIZE 3 2010-04-07 "corosync Man Page" "Corosync Cluster Engine Programmer's Manual"
> +.SH NAME
> +cpg_model_initialize \- Create a new connection to the CPG service
> +.SH SYNOPSIS
> +.B #include <corosync/cpg.h>
> +.sp
> +.BI "cs_error_t cpg_model_initialize(cpg_handle_t *" handle ", cpg_model_t " model ", cpg_model_data_t *" model_data ", void *" context ");
> +
> +.SH DESCRIPTION
> +The
> +.B cpg_model_initialize
> +function is used to initialize a connection to the closed process groups API.
> +.PP
> +Each application may have several connections to the CPG API. Each application
> +uses the
> +.I handle
> +argument to uniquely identify the connection. The
> +.I handle
> +argument is then used in other function calls to identify the connection to be used
> +for communication with the CPG service.
> +.PP
> +Argument
> +.I model
> +is used to explicitly choose set of callbacks and internal parameters. Currently only model
> +.I CPG_MODEL_V1
> +is defined.
> +.PP
> +Callbacks and internal parameters are passed by
> +.I model_data
> +argument. This is casted pointer (idea is similar as in sockaddr function) to one of structures
> +corresponding to chosen model. Currently only
> +.I cpg_model_v1_data_t
> +is needed.
> +.SH MODEL_V1
> +The
> +.I MODEL_V1
> +is backwards compatible with original callbacks initialized by
> +.I cpg_initialize
> +but new callback
> +.I cpg_totem_confchg_fn
> +is defined.
> +.PP
> +Every time an CPG event occurs within the joined group, one of the callbacks specified by the argument
> +.I callbacks
> +is called. The callback functions are described by the following type definitions:
> +.PP
> +.PP
> +.IP
> +.RS
> +.ne 18
> +.nf
> +.ta 4n 20n 32n
> +
> +typedef void (*cpg_deliver_fn_t) (
> + cpg_handle_t handle,
> + const struct cpg_name *group_name,
> + uint32_t nodeid,
> + uint32_t pid,
> + const void *msg,
> + size_t msg_len);
> +
> +
> +typedef void (*cpg_confchg_fn_t) (
> + cpg_handle_t handle,
> + const struct cpg_name *group_name,
> + const struct cpg_address *member_list, size_t member_list_entries,
> + const struct cpg_address *left_list, size_t left_list_entries,
> + const struct cpg_address *joined_list, size_t joined_list_entries);
> +
> +
> +typedef void (*cpg_totem_confchg_fn_t) (
> + cpg_handle_t handle,
> + struct cpg_ring_id ring_id,
> + uint32_t member_list_entries,
> + const uint32_t *member_list);
> +.ta
> +.fi
> +.RE
> +.IP
> +.PP
> +.PP
> +The
> +.I cpg_model_v1_data_t
> +structure is defined as:
> +.IP
> +.RS
> +.ne 18
> +.nf
> +.PP
> +typedef struct {
> + cpg_model_t model;
> + cpg_deliver_fn_t cpg_deliver_fn;
> + cpg_confchg_fn_t cpg_confchg_fn;
> + cpg_totem_confchg_fn_t cpg_totem_confchg_fn;
> +} cpg_model_v1_data_t;
> +.ta
> +.fi
> +.RE
> +.IP
> +.PP
> +When a configuration change occurs or a message is to be delivered one of the callbacks
> +is called from the
> +.B cpg_dispatch()
> +function. If a configuration change occurs,
> +.I cpg_confchg_fn
> +is called. If a delivery of a message occurs,
> +.I cpg_deliver_fn
> +is called.
> +When totem membership change occurs,
> +.I cpg_totem_confchg_fn
> +is called.
> +The
> +.I cpg_address
> +structure is defined
> +.IP
> +.RS
> +.ne 18
> +.nf
> +.PP
> +struct cpg_address {
> + unsigned int nodeid;
> + unsigned int pid;
> + unsigned int reason;
> +};
> +.ta
> +.fi
> +.RE
> +.IP
> +.PP
> +where nodeid is a 32 bit unique node identifier, pid is the process ID of the process that has joined/left the group
> +or sent the message, and reason is an integer code indicating why the node joined/left the group.
> +.PP
> +.IP
> +.RS
> +.ne 18
> +.nf
> +.PP
> +CPG_REASON_JOIN - the process joined a group using cpg_join().
> +CPG_REASON_LEAVE - the process left a group using cpg_leave()
> +CPG_REASON_NODEDOWN - the process left a group because the node left the cluster.
> +CPG_REASON_NODEUP - the process joined a group because it was already a member of a group on a node that has just joined the cluster
> +CPG_REASON_PROCDOWN - the process left a group without calling cpg_leave()
> +.ta
> +.fi
> +.RE
> +.IP
> +.PP
> +The
> +.I cpg_ring_id
> +structure is defined
> +.IP
> +.RS
> +.ne 18
> +.nf
> +.PP
> +struct cpg_ring_id {
> + uint32_t nodeid;
> + uint64_t seq;
> +};
> +.ta
> +.fi
> +.RE
> +.IP
> +.PP
> +where
> +.I nodeid
> +is if of node of current Totem leader and seq is increasing number.
> +
> +.PP
> +.SH RETURN VALUE
> +This call returns the CPG_OK value if successful, otherwise an error is returned.
> +.PP
> +.SH ERRORS
> +The errors are undocumented.
> +.SH "SEE ALSO"
> +.BR cpg_overview (8),
> +.BR cpg_initialize (3),
> +.BR cpg_finalize (3),
> +.BR cpg_fd_get (3),
> +.BR cpg_dispatch (3),
> +.BR cpg_join (3),
> +.BR cpg_leave (3),
> +.BR cpg_mcast_joined (3),
> +.BR cpg_membership_get (3)
> +.BR cpg_zcb_alloc (3)
> +.BR cpg_zcb_free (3)
> +.BR cpg_zcb_mcast_joined (3)
> +.BR cpg_context_get (3)
> +.BR cpg_context_set (3)
> +.BR cpg_local_get (3)
> +.BR cpg_model_initialize (3)
> +
> +.PP
> diff --git a/trunk/man/cpg_overview.8 b/trunk/man/cpg_overview.8
> index 84d4c3b..1f268a5 100644
> --- a/trunk/man/cpg_overview.8
> +++ b/trunk/man/cpg_overview.8
> @@ -61,6 +61,7 @@ access the corosync services.
> .BR cpg_join (3),
> .BR cpg_leave (3),
> .BR cpg_mcast_joined (3),
> +.BR cpg_model_initialize (3),
> .BR cpg_membership_get (3)
> .BR cpg_zcb_alloc (3)
> .BR cpg_zcb_free (3)
> _______________________________________________
> Openais mailing list
> Openais at lists.linux-foundation.org
> https://lists.linux-foundation.org/mailman/listinfo/openais
More information about the Openais
mailing list