OpenClovis Logo

clClmApi.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2002-2012 OpenClovis Solutions Inc. All Rights Reserved.
3  *
4  * This file is available under a commercial license from the
5  * copyright holder or the GNU General Public License Version 2.0.
6  *
7  * The source code for this program is not published or otherwise
8  * divested of its trade secrets, irrespective of what has been
9  * deposited with the U.S. Copyright office.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * General Public License for more details.
15  *
16  * For more information, see the file COPYING provided with this
17  * material.
18  */
19 /*******************************************************************************
20  * ModuleName : gms
21  * File : clGmsApi.h
22  *******************************************************************************/
23 
24 /*******************************************************************************
25  * Description :
26  * This client function implements the SA Forum compliant cluster membership
27  * management.
28  *
29  * Component Manager (CPM) uses these functions to manage its node in the cluster.
30  * This service assumes that there is only one cluster in the system.
31  *
32  * An instance of this service (instantiated by the clGmsInitialize()
33  * function and identified by the gmsHandle) can view and manage the cluster.
34  * If a node joins/leaves/kicked out of the cluster then all the other nodes
35  * in the cluster and its group components are updated with the current status.
36  *
37  *********************************************************************************/
38 
39 /*********************************************************************************/
40 /****************************** Group Management Service**************************/
41 /*********************************************************************************/
42 /* */
43 /* clGmsClusterJoin */
44 /* clGmsClusterJoinAsync */
45 /* clGmsClusterLeave */
46 /* clGmsClusterLeaveAsync */
47 /* clGmsClusterLeaderElect */
48 /* clGmsClusterMemberEject */
49 /* */
50 /**********************************************************************************/
51 
66 #ifndef _CL_GMS_API_H
67 #define _CL_GMS_API_H
68 
69 # ifdef __cplusplus
70 extern "C" {
71 # endif
72 
73 #include <clCommon.h>
74 #include <clClmTmsCommon.h>
75 
76 /*=========================================================================
77  * Callback Functions:
78  *=======================================================================*/
79 
105  CL_IN ClGmsMemberEjectReasonT reasonCode);
106 
114 typedef struct {
115 
120 
122 
134 /*
135  * param: splitBrain to indicate calling leader algorithm is in split-brain or normal case
136  */
139  ClGmsNodeIdT *leaderNodeId,
140  ClGmsNodeIdT *deputyNodeId,
141  ClGmsClusterMemberT *memberJoinedOrLeft,
142  ClGmsGroupChangesT cond,
143  ClBoolT splitBrain
144  );
145 
146 
147 /*=========================================================================
148  * API Functions:
149  *=======================================================================*/
150 
151 /*
152  ************************************
153  * \brief Joins the cluster as a member.
154  *
155  * \par Header File:
156  * clGmsApi.h
157  *
158  * \param gmsHandle The handle, obtained through the clGmsInitialize() function,
159  * designating this particular initialization of the Group Membership Service.
160  * \param clusterManageCallbacks Callbacks for managing the cluster.
161  * \param credentials This is an integer value specifying the
162  * leadership credibility of the node. Larger the value higher is the
163  * possibility of the node becoming a leader. Member with creditials
164  * \c CL_GMS_INELIGIBLE_CREDENTIALS cannot participate in the leader election.
165  * \param timeout If the cluster join is not completed within this time,
166  * then the join request is timed out.
167  * \param nodeId Node ID of the member that will join the cluster.
168  * \param nodeName Name of the node that will join the cluster.
169  *
170  *
171  * \retval CL_ERR_INVALID_HANDLE If the handle passed to the function is not valid.
172  * The handle passed should have been obtained from the clGmsInitialize() function.
173  * \retval CL_ERR_TIMEOUT If the join request timed out.
174  * \retval CL_ERR_INVALID_PARAMETER If any of the input parameters are invalid.
175  * \retval CL_ERR_NULL_POINTER If either of the parameters \e clusterManageCallbacks
176  * or \e nodeName are NULL.
177  * \retval CL_ERR_TRY_AGAIN: GMS server is not ready to process the request.
178 
179  *
180  * \par Description:
181  * This function is used to include a node into the the cluster as a member.
182  * Success or failure is reported via return value
183  * Members who have registered for tracking, get notified by tracking callback.
184  *
185  * \par Library File:
186  * ClGms
187  *
188  * \sa clGmsClusterLeave()
189  *
190  */
191 extern ClRcT clGmsClusterJoin(
192  CL_IN const ClGmsHandleT gmsHandle,
193  CL_IN const ClGmsClusterManageCallbacksT* const clusterManageCallbacks,
194  CL_IN const ClGmsLeadershipCredentialsT credentials,
195  CL_IN const ClTimeT timeout,
196  CL_IN const ClGmsNodeIdT nodeId,
197  CL_IN const ClNameT* const nodeName);
198 
199 
200 /*
201  ************************************
202  * \brief Asynchronously joins the cluster as a member.
203  *
204  * \par Header File:
205  * clGmsApi.h
206  *
207  * \param gmsHandle The handle, obtained through the clGmsInitialize() function,
208  * designating this particular initialization of the Group Membership Service
209  * \param clusterManageCallbacks Callbacks for managing the cluster.
210  * \param credentials This is an integer value specifying the
211  * leadership credibility of the node. Larger the value higher is the
212  * possibility of the node becoming a leader. Member with creditials
213  * \c CL_GMS_INELIGIBLE_CREDENTIALS cannot participate in the leader election.
214  * \param timeout If the cluster join is not completed within this time,
215  * then the join request is timed out.
216  * \param nodeId Node ID of the member that will join the cluster.
217  * \param nodeName Name of the node that will join the cluster.
218  *
219  *
220  * \retval CL_ERR_INVALID_HANDLE If the handle passed to the function is not valid.
221  * The handle passed should have been obtained from the clGmsInitialize() function.
222  * \retval CL_GMS_ERR_JOIN_DENIED If the node is already part of the cluster.
223  * \retval CL_ERR_INVALID_PARAMETER If any of the input parameters are invalid.
224  * \retval CL_ERR_NULL_POINTER If either of the parameters \e clusterManageCallbacks
225  * or \e nodeName are NULL.
226  *
227  * \par Description:
228  * This function is used to asynchronously include a node into the cluster as a member.
229  * Success is reported via return value.
230  * Members that have registered for tracking get notified by tracking
231  * callback.
232  *
233  * \par Library File:
234  * ClGms
235  *
236  * \sa clGmsClusterJoin()
237  *
238  */
239 extern ClRcT clGmsClusterJoinAsync(
240  CL_IN const ClGmsHandleT gmsHandle,
241  CL_IN const ClGmsClusterManageCallbacksT* const clusterManageCallbacks,
242  CL_IN const ClGmsLeadershipCredentialsT credentials,
243  CL_IN const ClGmsNodeIdT nodeId,
244  CL_IN const ClNameT* const nodeName);
245 
246 
247 /*
248  ************************************
249  * \brief Leaves the cluster.
250  *
251  * \par Header File:
252  * clGmsApi.h
253  *
254  * \param gmsHandle The handle, obtained through the clGmsInitialize() function,
255  * designating this particular initialization of the Group Membership Service
256  * \param timeout If the cluster leave operation is not completed within this time,
257  * then the leave request is timed out.
258  * \param nodeId Node ID of the member that is leaving the cluster.
259  *
260  * \retval CL_ERR_INVALID_HANDLE If the handle passed to the function is not valid.
261  * The handle passed should have been obtained from the clGmsInitialize() function..
262  * \retval CL_ERR_INVALID_PARAMETER If any of the input parameters are invalid.
263  *
264  * \par Description:
265  * This function is used to make a node leave the cluster. Once the node leaves the cluster
266  * and the groups/components will be expelled and
267  * a reason for expulsion will be returned through their
268  * callback functions.
269  *
270  * \par Library File:
271  * ClGms
272  *
273  * \sa clGmsClusterJoin()
274  *
275  */
276 extern ClRcT clGmsClusterLeave(
277  CL_IN ClGmsHandleT gmsHandle,
278  CL_IN ClTimeT timeout,
279  CL_IN ClGmsNodeIdT nodeId);
280 
281 extern ClRcT clGmsClusterLeaveNative(
282  CL_IN ClGmsHandleT gmsHandle,
283  CL_IN ClTimeT timeout,
284  CL_IN ClGmsNodeIdT nodeId);
285 
286 
287 /*
288  ************************************
289  * \brief Leaves the cluster asynchronously.
290  *
291  * \par Header File:
292  * clGmsApi.h
293  *
294  * \param gmsHandle The handle, obtained through the clGmsInitialize() function,
295  * designating this particular initialization of the Group Membership Service
296  * \param nodeId Node ID of the member to be ejected out.
297  *
298  * \retval CL_ERR_INVALID_HANDLE If the handle passed to the function is not valid.
299  * The handle passed should have been obtained from the clGmsInitialize() function.
300  * \retval CL_ERR_INVALID_PARAMETER If any of the input parameters are invalid.
301  *
302  * \par Description:
303  * This function is used to make a node leave the cluster asynchronously. Once the node leaves the cluster
304  * and the groups/components will be expelled and
305  * a reason for expulsion will be returned through their
306  * callback functions.
307  *
308  * \par Library File:
309  * ClGms
310  *
311  * \sa clGmsClusterLeave()
312  *
313  */
314 extern ClRcT clGmsClusterLeaveAsync(
315  CL_IN ClGmsHandleT gmsHandle,
316  CL_IN ClGmsNodeIdT nodeId);
317 
318 
346  CL_IN ClGmsHandleT gmsHandle,
347  CL_IN ClGmsNodeIdT preferredLeader,
350  CL_INOUT ClBoolT *leadershipChanged);
351 
352 
353 
390  CL_IN ClGmsHandleT gmsHandle,
391  CL_IN ClGmsNodeIdT nodeId,
393 
394 
395 #ifdef __cplusplus
396 }
397 #endif
398 
399 #endif /* _CL_GMS_CLUSTER_MANAGE_API_H_ */
400 
Typical defines found in any software project.
Header file of Group Membership Service APIs.
ClGmsNodeIdT deputy
Node marked as deputy.
Definition: clClmTmsCommon.h:23
ClBoolT leadershipChanged
To check whether the leader has changed since the last view.
Definition: clClmTmsCommon.h:28
ClGmsNodeIdT leader
Node ID of current leader.
Definition: clClmTmsCommon.h:18
ClUint32T ClRcT
Clovis return code type.
Definition: clCommon.h:168
#define CL_INOUT
CL_INOUT macro assists in clearly defining arguments of an API, but has no actual meaning.
Definition: clCommon.h:108
ClInt64T ClTimeT
Time duration specified in nanoseconds.
Definition: clCommon.h:154
#define CL_IN
CL_IN macro assists in clearly defining arguments of an API, but has no actual meaning.
Definition: clCommon.h:106
ClHandleT ClGmsHandleT
Handle for using the GMS API.
Definition: clClmTmsCommon.h:137
void(* ClGmsClusterMemberEjectCallbackT)(CL_IN ClGmsMemberEjectReasonT reasonCode)
Callback for indicating that member was expelled from the cluster.
Definition: clClmApi.h:104
ClGmsMemberEjectReasonT
Reason codes for ejecting the user from cluster/group.
Definition: clClmTmsCommon.h:620
ClUint32T ClGmsLeadershipCredentialsT
Credentials for leader election.
Definition: clClmTmsCommon.h:150
ClRcT clGmsClusterMemberEject(CL_IN ClGmsHandleT gmsHandle, CL_IN ClGmsNodeIdT nodeId, CL_IN ClGmsMemberEjectReasonT reason)
Forcibly removes a member from the cluster.
ClRcT clGmsClusterLeaderElect(CL_IN ClGmsHandleT gmsHandle, CL_IN ClGmsNodeIdT preferredLeader, CL_INOUT ClGmsNodeIdT *leader, CL_INOUT ClGmsNodeIdT *deputy, CL_INOUT ClBoolT *leadershipChanged)
Initiate leader election synchronously.
ClUint32T ClGmsNodeIdT
Node ID – Unique and consistent identifier of a node.
Definition: clClmTmsCommon.h:143
ClGmsGroupChangesT
Enumerator and structure of member status notification.
Definition: clClmTmsCommon.h:463
ClRcT(* ClGmsLeaderElectionAlgorithmT)(ClGmsClusterNotificationBufferT buffer, ClGmsNodeIdT *leaderNodeId, ClGmsNodeIdT *deputyNodeId, ClGmsClusterMemberT *memberJoinedOrLeft, ClGmsGroupChangesT cond, ClBoolT splitBrain)
Signature of the leader election algorithm used in the GMS engine .
Definition: clClmApi.h:137
A name.
Definition: clCommon.h:197
This structure contains the cluster managing callbacks provided at the joining time by the member.
Definition: clClmApi.h:114
ClGmsClusterMemberEjectCallbackT clGmsMemberEjectCallback
Pointer to the Eject Callback funtion.
Definition: clClmApi.h:119
This structure describes one member (or node) of the cluster.
Definition: clClmTmsCommon.h:244
Buffer to convey the view: the list of nodes and their status.
Definition: clClmTmsCommon.h:337

Generated on Tue Jan 10 10:29:15 PST 2012 for OpenClovis SDK using Doxygen