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 * The meaning of the unode field is not defined by this specification.
97 * 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 struct oc_member_uniqueid_s {
102 unsigned m_instance;
103 oc_node_id_t unode;
104 };
105 /*
106 * This enumeration is used both to indicated the type of an event
107 * received, and to request the types of events one wants delivered.
108 * (see oc_member_request_events() and oc_member_etype() for more
109 * details on how this is used).
110 */
111
112 enum oc_member_eventtype_e {
113 OC_NOT_MEMBERSHIP, /* Not a (valid) membership event */
114 OC_FULL_MEMBERSHIP, /* full membership update */
115 OC_INCR_MEMBERSHIP, /* incremental membership update */
116 };
117
118
119 #ifdef __cplusplus
120 extern "C" {
121 alanr 1.1 #endif
122
123 /*
124 * Returns 0 for equal node_ids,
125 * negative for node id l less than node id r
126 * positive for node id l greater than node id r
|
127 alanr 1.2 *
128 * No meaning may be ascribed to the fact that a particular
129 * node id is greater or less than some other node id.
130 * The comparison operator is provided primarily for
131 * equality comparisons, and secondarily for use in
132 * sorting them into a canonical order.
|
133 alanr 1.1 */
134 int oc_cmp_node_id(oc_node_id_t l, oc_node_id_t r);
135
136
137 /* Return our local node id */
138 int oc_localnodeid(oc_node_id_t* us, oc_cluster_handle_t handle);
139 /*
140 * On failure these functions return -1:
141 * The following errno values are defined:
142 * EINVAL invalid handle argument
143 * EL2HLT cluster software not currently running
144 */
145
146 /* What kind of event did we get? */
147 /* (see oc_member_request_events() for more details) */
148 oc_member_eventtype_t oc_member_etype(const void* edata, size_t esize);
149
|
150 alanr 1.2 /*
151 * oc_member_uniqueid() returns the unique identifier associated
152 * with this membership event. See the description in the typedef
153 * for more details.
154 */
|
155 alanr 1.1 int oc_member_uniqueid(const void* edata, size_t esize,
156 oc_member_uniqueid_t* u);
157 /*
158 * Failure of these functions return -1.
159 * The following errno values are defined:
160 * EL2HLT cluster software not currently running
161 * EINVAL edata does not refer to a membership event
162 */
163
164 /* How many nodes of each category do we have? */
165 int oc_member_n_nodesjoined(const void* edata, size_t esize);
|
166 alanr 1.2 int oc_member_n_nodesgone(void* edata, size_t esize);
|
167 alanr 1.1 int oc_member_n_nodesconst(void* edata, size_t esize);
168 /*
169 * Failure of these functions return -1.
170 * The following errno values are defined:
171 * EL2HLT cluster software not currently running
172 * EINVAL edata does not refer to a membership event
173 * ENOSYS edata refers to an OC_INCR_MEMBERSHIP update, and
174 * oc_member_n_nodesconst() was called.
175 */
176
177 /* What nodes of each category do we have? */
178 oc_node_id_t* oc_member_nodesjoined(const void* edata, size_t esize);
|
179 alanr 1.2 oc_node_id_t* oc_member_nodesgone(void* edata, size_t esize);
|
180 alanr 1.1 oc_node_id_t* oc_member_nodesconst(void* edata, size_t esize);
181 /*
182 * Failure of these functions return NULL.
183 * The following errno values are defined:
184 * EL2HLT cluster software not currently running
185 * EINVAL edata does not refer to a membership event
186 * ENOSYS edata refers to an OC_INCR_MEMBERSHIP update, and
187 * oc_member_nodesconst() was called.
188 */
189
190 /*
191 *
192 * OC_NO_MEMBERSHIP
193 * No membership events will be delivered. This is the default on opening
194 * a membership event connection.
195 *
196 * OC_FULL_MEMBERSHIP
197 * Deliver all membership information including information on
198 * members that didn't change. In this mode, the oc_member_nodesconst()
199 * call is supported.
200 *
201 alanr 1.1 * OC_INCR_MEMBERSHIP
202 * Deliver only changed membership events. In this mode, calls to
203 * oc_member_nodesconst(), et al. are not supported.
204 *
205 * Setting OC_FULL_MEMBERSHIP or OC_INCR_MEMBERSHIP will result in the
206 * delivery of a single OC_FULL_MEMBERSHIP event soon after making
207 * this call. Subsequent events will be delivered as received in the
|
208 alanr 1.2 * requested style (incremental or full). Because events may already
209 * be pending when this operation is issued, no guarantee can be made
210 * regarding when this triggered event will be delivered.
211 *
|
212 alanr 1.1 */
213 int oc_member_request_events(oc_member_eventtype_t etype, oc_ev_t token);
214 /*
215 * On failure this function returns -1:
216 * The following errno values are defined:
217 * EINVAL invalid etype or handle argument
218 * EL2HLT cluster software not currently running
219 * EBADF invalid oc_ev_t token parameter
220 */
221
222 /*
223 * if l.m_instance < r.m_instance then return -1
224 * if r.m_instance > r.m_instance then return 1
225 * if l.m_instance == r.m_instance and l.unode == r.unode
226 * then return 0
227 * otherwise return 2
228 */
229 int oc_cmp_uniqueid(const oc_member_uniqueid_t l, const oc_member_uniqueid_t r);
230
231 #ifdef __cplusplus
232 }
233 alanr 1.1 #endif
234
235 #endif
|
Return to
oc_membership.h
CVS log
Up to [OpenCF] / specs / membership