1 alanr 1.1 #ifndef OCF_OC_MEMBERSHIP_H
2 # define OCF_OC_MEMBERSHIP_H
3 /*
4 * <ocf/oc_membership.h> - membership APIs (version 0.1)
5 *
6 * The structures and functions in this header file work closely with
7 * the oc_event.h event infrastructure. All (edata, esize) parameters
8 * to functions in this header file refer to membership event bodies.
9 * It is expected that all such are received by this mechanism.
10 *
11 *
12 * There are a few things in this header file which don't really belong here
13 * but are needed and they aren't in any other header file.
14 *
15 * These are:
16 * definition of oc_node_id_t
17 * oc_cluster_handle_t
18 *
19 * Maybe we ought to put common types into an <ocf/oc_types.h>
20 *
21 * The oc_cmp_node_id() and oc_localnodeid() functions also belong in
22 alanr 1.1 * some more global header file.
23 *
24 * oc_member_eventttype_t and * oc_member_uniqueid_t are membership-unique
25 * and don't belong in a set of ocf-common header files (IMHO)
26 *
27 * Copyright (C) 2002 Alan Robertson <alanr@unix.sh>
28 *
29 * This copyright will be assigned to the Free Standards Group
30 * in the future.
31 *
32 * This library is free software; you can redistribute it and/or
33 * modify it under the terms of version 2.1 of the GNU Lesser General Public
34 * License as published by the Free Software Foundation.
35 *
36 * This library is distributed in the hope that it will be useful,
37 * but WITHOUT ANY WARRANTY; without even the implied warranty of
38 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
39 * Lesser General Public License for more details.
40 *
41 * You should have received a copy of the GNU Lesser General Public
42 * License along with this library; if not, write to the Free Software
43 alanr 1.1 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
44 *
45 */
46
47 #include <stddef.h>
48 #include <ocf/oc_event.h>
49
50 #ifdef HAVE_UUID_UUID_H
51 # include <uuid/uuid.h>
52 #else
53
54 typedef unsigned char uuid_t[16];
55
56 #endif
57 /* controversial? */
58 typedef void * oc_cluster_handle_t;
59 typedef uuid_t oc_node_id_t;
60 typedef enum oc_member_eventtype_e oc_member_eventtype_t;
61 typedef struct oc_member_uniqueid_s oc_member_uniqueid_t;
62
63 /*
64 alanr 1.1 * A few words about the oc_node_id_t:
65 *
|
66 alanr 1.2 * An oc_node_id_t is assigned to a node no later than when it first
67 * joins a cluster, and it will not change while that node is active
|
68 alanr 1.1 * in some partition in the cluster. It is normally expected to
69 * be assigned to a node, and not changed afterwards except by
70 * adminstrative intervention.
71 *
|
72 alanr 1.2 * The mechanism for assigning oc_node_id_t's to nodes is outside the
73 * scope of this specification. The only basic operation which
74 * can be performed on these objects is comparison.
75 *
|
76 alanr 1.1 * See oc_cmp_node_id() for comparisons between them.
77 */
78
79 /*
80 * oc_member_uniqueid_t
81 * The values of these fields are guaranteed to be the same across
82 * all nodes within a given partition, and guaranteed to be different
83 * between all active partitions in the cluster.
84 *
85 * In other words, if you exchange current oc_member_uniqueid_t objects
86 * with another cluster node, you can tell with certainty, whether or not
87 * you and the other node are currently members of the same partition.
88 *
89 * The m_instance field is guaranteed to be unique to a particular
90 * membership instance while that node is active in the cluster.
91 * If a node is shut down and restarts, then the m_instance might
92 * repeat a value it had in the past.
93 *
94 * See oc_cmp_uniqueid() for comparing them.
|
95 alanr 1.2 *
|
96 alanr 1.3 * The meaning of the uniqueid field is not defined by this specification.
|
97 alanr 1.2 * It may be the node_id of a node in the cluster or it may be a unique
98 * checksum or it may be some other value. All that is specified is that
99 * it and the m_instance are unique when taken as a whole.
|
100 alanr 1.1 */
|
101 alanr 1.3 typedef unsigned char oc_mbr_uuid[16];
|
102 alanr 1.1 struct oc_member_uniqueid_s {
103 unsigned m_instance;
|
104 alanr 1.3 oc_mbr_uniqueid uniqueid;
|
105 alanr 1.1 };
106 /*
107 * This enumeration is used both to indicated the type of an event
108 * received, and to request the types of events one wants delivered.
109 * (see oc_member_request_events() and oc_member_etype() for more
110 * details on how this is used).
111 */
112
113 enum oc_member_eventtype_e {
114 OC_NOT_MEMBERSHIP, /* Not a (valid) membership event */
115 OC_FULL_MEMBERSHIP, /* full membership update */
116 OC_INCR_MEMBERSHIP, /* incremental membership update */
117 };
118
119
120 #ifdef __cplusplus
121 extern "C" {
122 #endif
123
124 /*
125 * Returns 0 for equal node_ids,
126 alanr 1.1 * negative for node id l less than node id r
127 * positive for node id l greater than node id r
|
128 alanr 1.2 *
129 * No meaning may be ascribed to the fact that a particular
130 * node id is greater or less than some other node id.
131 * The comparison operator is provided primarily for
132 * equality comparisons, and secondarily for use in
133 * sorting them into a canonical order.
|
134 alanr 1.1 */
135 int oc_cmp_node_id(oc_node_id_t l, oc_node_id_t r);
136
137
138 /* Return our local node id */
139 int oc_localnodeid(oc_node_id_t* us, oc_cluster_handle_t handle);
140 /*
141 * On failure these functions return -1:
142 * The following errno values are defined:
143 * EINVAL invalid handle argument
144 * EL2HLT cluster software not currently running
145 */
146
147 /* What kind of event did we get? */
148 /* (see oc_member_request_events() for more details) */
149 oc_member_eventtype_t oc_member_etype(const void* edata, size_t esize);
150
|
151 alanr 1.2 /*
152 * oc_member_uniqueid() returns the unique identifier associated
153 * with this membership event. See the description in the typedef
154 * for more details.
155 */
|
156 alanr 1.1 int oc_member_uniqueid(const void* edata, size_t esize,
157 oc_member_uniqueid_t* u);
158 /*
159 * Failure of these functions return -1.
160 * The following errno values are defined:
161 * EL2HLT cluster software not currently running
162 * EINVAL edata does not refer to a membership event
163 */
164
165 /* How many nodes of each category do we have? */
166 int oc_member_n_nodesjoined(const void* edata, size_t esize);
|
167 alanr 1.2 int oc_member_n_nodesgone(void* edata, size_t esize);
|
168 alanr 1.1 int oc_member_n_nodesconst(void* edata, size_t esize);
169 /*
170 * Failure of these functions return -1.
171 * The following errno values are defined:
172 * EL2HLT cluster software not currently running
173 * EINVAL edata does not refer to a membership event
174 * ENOSYS edata refers to an OC_INCR_MEMBERSHIP update, and
175 * oc_member_n_nodesconst() was called.
176 */
177
178 /* What nodes of each category do we have? */
179 oc_node_id_t* oc_member_nodesjoined(const void* edata, size_t esize);
|
180 alanr 1.2 oc_node_id_t* oc_member_nodesgone(void* edata, size_t esize);
|
181 alanr 1.1 oc_node_id_t* oc_member_nodesconst(void* edata, size_t esize);
182 /*
183 * Failure of these functions return NULL.
184 * The following errno values are defined:
185 * EL2HLT cluster software not currently running
186 * EINVAL edata does not refer to a membership event
187 * ENOSYS edata refers to an OC_INCR_MEMBERSHIP update, and
188 * oc_member_nodesconst() was called.
189 */
190
191 /*
192 *
193 * OC_NO_MEMBERSHIP
194 * No membership events will be delivered. This is the default on opening
195 * a membership event connection.
196 *
197 * OC_FULL_MEMBERSHIP
198 * Deliver all membership information including information on
199 * members that didn't change. In this mode, the oc_member_nodesconst()
200 * call is supported.
201 *
202 alanr 1.1 * OC_INCR_MEMBERSHIP
203 * Deliver only changed membership events. In this mode, calls to
204 * oc_member_nodesconst(), et al. are not supported.
205 *
206 * Setting OC_FULL_MEMBERSHIP or OC_INCR_MEMBERSHIP will result in the
207 * delivery of a single OC_FULL_MEMBERSHIP event soon after making
208 * this call. Subsequent events will be delivered as received in the
|
209 alanr 1.2 * requested style (incremental or full). Because events may already
210 * be pending when this operation is issued, no guarantee can be made
211 * regarding when this triggered event will be delivered.
212 *
|
213 alanr 1.1 */
214 int oc_member_request_events(oc_member_eventtype_t etype, oc_ev_t token);
215 /*
216 * On failure this function returns -1:
217 * The following errno values are defined:
218 * EINVAL invalid etype or handle argument
219 * EL2HLT cluster software not currently running
220 * EBADF invalid oc_ev_t token parameter
221 */
222
223 /*
224 * if l.m_instance < r.m_instance then return -1
225 * if r.m_instance > r.m_instance then return 1
|
226 alanr 1.3 * if l.m_instance == r.m_instance and l.uniqueid == r.uniqueid
|
227 alanr 1.1 * then return 0
228 * otherwise return 2
229 */
230 int oc_cmp_uniqueid(const oc_member_uniqueid_t l, const oc_member_uniqueid_t r);
231
232 #ifdef __cplusplus
233 }
234 #endif
235
236 #endif
|
Return to
oc_membership.h
CVS log
Up to [OpenCF] / specs / membership