man/cpg_initialize.3

   1 .\"/*
   2 .\" * Copyright (c) 2006 Red Hat, Inc.
   3 .\" *
   4 .\" * All rights reserved.
   5 .\" *
   6 .\" * Author: Patrick Caulfield <pcaulfie@redhat.com>
   7 .\" *
   8 .\" * This software licensed under BSD license, the text of which follows:
   9 .\" *
  10 .\" * Redistribution and use in source and binary forms, with or without
  11 .\" * modification, are permitted provided that the following conditions are met:
  12 .\" *
  13 .\" * - Redistributions of source code must retain the above copyright notice,
  14 .\" *   this list of conditions and the following disclaimer.
  15 .\" * - Redistributions in binary form must reproduce the above copyright notice,
  16 .\" *   this list of conditions and the following disclaimer in the documentation
  17 .\" *   and/or other materials provided with the distribution.
  18 .\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
  19 .\" *   contributors may be used to endorse or promote products derived from this
  20 .\" *   software without specific prior written permission.
  21 .\" *
  22 .\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  23 .\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  26 .\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  27 .\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  28 .\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  29 .\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  30 .\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  31 .\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  32 .\" * THE POSSIBILITY OF SUCH DAMAGE.
  33 .\" */
  34 .TH CPG_INITIALIZE 3 2004-08-31 "openais Man Page" "Openais Programmer's Manual"
  35 .SH NAME
  36 cpg_initialize \- Create a new connection to the CPG service
  37 .SH SYNOPSIS
  38 .B #include <openais/cpg.h>
  39 .sp
  40 .BI "int cpg_initialize(cpg_handle_t *" handle ", cpg_callbacks_t *" callbacks ");
  41 .SH DESCRIPTION
  42 The
  43 .B cpg_initialize
  44 function is used to initialize a connection to the closed process groups API.
  45 .PP
  46 Each application may have several connections to the CPG API.  Each  application
  47 uses the
  48 .I handle
  49 argument to uniquely identify the connection.  The
  50 .I handle
  51 argument is then used in other function calls to identify the connection to be used
  52 for communication with the CPG service.
  53 .PP
  54 Every time an CPG event occurs within the joined group, one of the callbacks specified by the argument
  55 .I callbacks
  56 is called.  The callback functions are described by the following type definitions:
  57 .PP
  58 .PP
  59 .IP
  60 .RS
  61 .ne 18
  62 .nf
  63 .ta 4n 20n 32n
  64
  65 typedef void (*cpg_deliver_fn_t) (
  66         cpg_handle_t handle,
  67         struct cpg_name *group_name,
  68         uint32_t nodeid,
  69         uint32_t pid,
  70         void *msg,
  71         int msg_len);
  72
  73
  74 typedef void (*cpg_confchg_fn_t) (
  75         cpg_handle_t handle,
  76         struct cpg_name *group_name,
  77         struct cpg_address *member_list, int member_list_entries,
  78         struct cpg_address *left_list, int left_list_entries,
  79         struct cpg_address *joined_list, int joined_list_entries);
  80 .ta
  81 .fi
  82 .RE
  83 .IP
  84 .PP
  85 .PP
  86 The
  87 .I callbacks
  88 argument is of the type:
  89 .IP
  90 .RS
  91 .ne 18
  92 .nf
  93 .PP
  94 typedef struct {
  95         cpg_deliver_fn_t cpg_deliver_fn;
  96         cpg_confchg_fn_t cpg_confchg_fn;
  97 } cpg_callbacks_t;
  98 .ta
  99 .fi
 100 .RE
 101 .IP
 102 .PP
 103 When a configuration change occurs or a message is to be delivered one of the callbacks
 104 is called from the
 105 .B cpg_dispatch()
 106 function.  If a configuration change occurs,
 107 .I cpg_confchg_fn
 108 is called.  If a delivery of a message occurs,
 109 .I cpg_deliver_fn
 110 is called.
 111
 112 The
 113 .I cpg_address
 114 structure is defined
 115 .IP
 116 .RS
 117 .ne 18
 118 .nf
 119 .PP
 120 struct cpg_address {
 121         unsigned int nodeid;
 122         unsigned int pid;
 123         unsigned int reason;
 124 };
 125 .ta
 126 .fi
 127 .RE
 128 .IP
 129 .PP
 130 where nodeid is a 32 bit unique node identifier, pid is the process ID of the process that has joined/left the group
 131 or sent the message, and reason is an integer code indicating why the node join/left the group.
 132 .PP
 133 .IP
 134 .RS
 135 .ne 18
 136 .nf
 137 .PP
 138 CPG_REASON_JOIN     - the process joined a group using cpg_join().
 139 CPG_REASON_LEAVE    - the process left a group using cpg_leave()
 140 CPG_REASON_NODEDOWN - the process left a group because the node left the cluster.
 141 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
 142 CPG_REASON_PROCDOWN - the process left a group without calling cpg_leave()
 143 .ta
 144 .fi
 145 .RE
 146 .IP
 147 .PP
 148 .SH RETURN VALUE
 149 This call returns the CPG_OK value if successful, otherwise an error is returned.
 150 .PP
 151 .SH ERRORS
 152 The errors are undocumented.
 153 .SH "SEE ALSO"
 154 .BR cpg_overview (8),
 155 .BR cpg_finalize (3),
 156 .BR cpg_fd_get (3),
 157 .BR cpg_dispatch (3),
 158 .BR cpg_join (3),
 159 .BR cpg_leave (3),
 160 .BR cpg_mcast_joined (3),
 161 .BR cpg_membership_get (3)
 162 .PP