OpenClovis Logo

clClmTmsCommon.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 : clClmTmsCommon.h
22  ******************************************************************************/
23 
24 /*******************************************************************************
25  * Description :
26  *
27  * This is the viewer API for the Group Membership Service (GMS). It allows
28  * query and asynhronous tracking of GMS groups. It does not provide for
29  * managing groups (creating, deleteing, joining, leaving). For that purpose
30  * separate additional API components are provided.
31  *
32  * There are two types of GMS groups covered by this service:
33  *
34  * - Cluster membership service -- A special type of group membership, where
35  * the members are the [compuing] nodes (processors) in the cluster.
36  *
37  * - Generalized component (or process) groups -- these are groups of
38  * arbitrary software components, running on the various nodes in the
39  * cluster. These components are commonly referred as group members.
40  *
41  * This API is provided by the GMS client library that can be linked to
42  * the application (directly or as part of the EO client environment).
43  *
44  * This API provides a superset of the SA Forum Cluster Membership (CLM)
45  * API, as specified in its B.01.01 version. A separate, SA Forum compliant
46  * API is provided also, as a separate header file supported by a separate
47  * set of API functions.
48  *
49  *
50  ******************************************************************************/
51 
52 
53 /******************************************************************************/
54 /****************************** GMS APIs **************************************/
55 /******************************************************************************/
56 /* */
57 /* clGmsInitialize */
58 /* clGmsFinalize */
59 /* clGmsClusterTrack */
60 /* clGmsClusterTrackStop */
61 /* clGmsClusterMemberGet */
62 /* clGmsClusterMemberGetAsync */
63 /* clGmsGroupTrack */
64 /* clGmsGroupTrackStop */
65 /* clGmsGetGroupInfo */
66 /* clGmsGroupsInfoListGet */
67 /* */
68 /******************************************************************************/
69 
84 #ifndef _CL_CLM_TMS_COMMON_H
85 #define _CL_CLM_TMS_COMMON_H
86 
87 # ifdef __cplusplus
88 extern "C" {
89 # endif
90 
91 #include <clCommon.h>
92 #include <clIocApi.h>
93 
94 /*******************************************************************************
95  * MACROS
96  ******************************************************************************/
97 
101 #define CL_GMS_MAX_ADDRESS_LENGTH 64
102 
106 #define CL_GMS_LOCAL_NODE_ID 0XFFFFFFFF
107 
111 #define CL_GMS_INVALID_HANDLE ((ClGmsHandleT)0)
112 
116 #define CL_GMS_INVALID_NODE_ID 0xffffffff
117 
121 #define CL_GMS_INELIGIBLE_CREDENTIALS 0x0
122 
126 #define CL_GMS_INVALID_GROUP_ID -1
127 
128 /*******************************************************************************
129  * TYPE DEFINITIONS
130  ******************************************************************************/
137 typedef ClHandleT ClGmsHandleT;
138 
139 
143 typedef ClUint32T ClGmsNodeIdT;
144 
145 
150 typedef ClUint32T ClGmsLeadershipCredentialsT;
151 
152 
157 typedef enum ClGmsNodeAddressFamilyT {
161  CL_GMS_AF_INET= 1,
162 
166  CL_GMS_AF_INET6 =2
167 } ClGmsNodeAddressFamilyT;
168 
169 
173 typedef enum ClGmsTrackFlagsT {
177  CL_GMS_TRACK_CURRENT = 0x01,
178 
183  CL_GMS_TRACK_CHANGES = 0x02,
184 
188  CL_GMS_TRACK_CHANGES_ONLY = 0x04
189 } ClGmsTrackFlagsT;
190 
191 
196 typedef enum ClGmsClusterChangesT {
200  CL_GMS_NODE_NO_CHANGE = 1,
201 
205  CL_GMS_NODE_JOINED = 2,
206 
210  CL_GMS_NODE_LEFT = 3,
211 
215  CL_GMS_NODE_RECONFIGURED = 4
216 } ClGmsClusterChangesT;
217 
218 
222 typedef struct ClGmsNodeAddressT {
227  ClGmsNodeAddressFamilyT family;
228 
232  ClUint16T length;
233 
237  ClUint8T value[CL_GMS_MAX_ADDRESS_LENGTH];
238 } ClGmsNodeAddressT;
239 
240 
244 typedef struct ClGmsClusterMemberT {
248  ClGmsNodeIdT nodeId __attribute__((__aligned__(8)));
249 
253  ClIocAddressT nodeAddress __attribute__((__aligned__(8)));
254 
258  ClGmsNodeAddressT nodeIpAddress __attribute__((__aligned__(8)));
259 
263  ClNameT nodeName __attribute__((__aligned__(8)));
264 
269  ClBoolT memberActive __attribute__((__aligned__(8)));
270 
274  ClTimeT bootTimestamp __attribute__((__aligned__(8)));
275 
279  ClUint64T initialViewNumber __attribute__((__aligned__(8)));
280 
288  ClGmsLeadershipCredentialsT credential __attribute__((__aligned__(8)));
289 
293  ClBoolT isCurrentLeader __attribute__((__aligned__(8)));
294 
298  ClBoolT isPreferredLeader __attribute__((__aligned__(8)));
299 
304  ClBoolT leaderPreferenceSet __attribute__((__aligned__(8)));
305 
311  ClVersionT gmsVersion __attribute__((__aligned__(8)));
312 
313 } ClGmsClusterMemberT __attribute__((__aligned__(8)));
314 
315 
320 typedef struct ClGmsClusterNotificationT {
324  ClGmsClusterMemberT clusterNode __attribute__((__aligned__(8)));
325 
329  ClGmsClusterChangesT clusterChange;
330 
331 } ClGmsClusterNotificationT __attribute__((__aligned__(8)));
332 
333 
337 typedef struct ClGmsClusterNotificationBufferT {
341  ClUint64T viewNumber __attribute__((__aligned__(8)));
342 
346  ClUint32T numberOfItems;
347 
351  ClGmsClusterNotificationT *notification;
352 
356  ClGmsNodeIdT leader;
357 
361  ClGmsNodeIdT deputy;
362 
366  ClBoolT leadershipChanged;
367 
368 } ClGmsClusterNotificationBufferT __attribute__((__aligned__(8)));
369 
370 
374 typedef ClNameT ClGmsGroupNameT;
375 
376 
380 typedef ClUint32T ClGmsGroupIdT;
381 
382 
386 typedef ClNameT ClGmsMemberNameT;
387 
388 
392 typedef ClUint32T ClGmsMemberIdT;
393 
394 
402 typedef struct ClGmsGroupParamsT {
403  /* Specifies if the group needs to create IOC multicast address
404  */
405  ClBoolT isIocGroup;
406 
407  /* for future implementations
408  */
409  char unused [256];
410 } ClGmsGroupParamsT;
411 
412 
416 typedef struct ClGmsGroupMemberT {
420  ClGmsHandleT handle __attribute__((__aligned__(8)));
424  ClGmsMemberIdT memberId __attribute__((__aligned__(8)));
425 
429  ClIocAddressT memberAddress __attribute__((__aligned__(8)));
430 
434  ClGmsMemberNameT memberName __attribute__((__aligned__(8)));
435 
439  ClBoolT memberActive __attribute__((__aligned__(8)));
440 
444  ClTimeT joinTimestamp __attribute__((__aligned__(8)));
445 
449  ClUint64T initialViewNumber __attribute__((__aligned__(8)));
450 
455  ClGmsLeadershipCredentialsT credential __attribute__((__aligned__(8)));
456 
457 } ClGmsGroupMemberT __attribute__((__aligned__(8)));
458 
459 
463 typedef enum ClGmsGroupChangesT {
467  CL_GMS_MEMBER_NO_CHANGE = 1,
468 
472  CL_GMS_MEMBER_JOINED = 2,
473 
477  CL_GMS_MEMBER_LEFT = 3,
478 
482  CL_GMS_MEMBER_RECONFIGURED = 4,
483 
487  CL_GMS_LEADER_ELECT_API_REQUEST = 5
488 } ClGmsGroupChangesT;
489 
490 
494 typedef struct ClGmsGroupNotificationT {
498  ClGmsGroupMemberT groupMember __attribute__((__aligned__(8)));
499 
503  ClGmsGroupChangesT groupChange;
504 
505 } ClGmsGroupNotificationT;
506 
507 
511 typedef struct ClGmsGroupNotificationBufferT {
512 
516  ClUint64T viewNumber __attribute__((__aligned__(8)));
517 
521  ClUint32T numberOfItems;
522 
526  ClGmsGroupNotificationT *notification;
527 
531  ClGmsMemberIdT leader;
532 
536  ClGmsMemberIdT deputy;
537 
541  ClBoolT leadershipChanged;
542 
543 } ClGmsGroupNotificationBufferT __attribute__((__aligned__(8)));
544 
545 
549 typedef struct ClGmsGroupInfoT {
553  ClGmsGroupNameT groupName;
554 
558  ClGmsGroupIdT groupId;
559 
563  ClGmsGroupParamsT groupParams;
564 
568  ClUint32T noOfMembers;
569 
573  ClBoolT setForDelete;
574 
578  ClIocMulticastAddressT iocMulticastAddr;
579 
583  ClTimeT creationTimestamp;
584 
588  ClTimeT lastChangeTimestamp;
589 
590 } ClGmsGroupInfoT;
591 
592 
596 typedef struct ClGmsGroupInfoListT {
600  ClUint32T noOfGroups;
601 
605  ClGmsGroupInfoT *groupInfoList;
606 } ClGmsGroupInfoListT;
607 
608 
612 #define LEADER_ELECTION_ALGORITHM "LeaderElectionAlgorithm"
613 
614 /* Default boot election timeout */
615 #define CL_GMS_DEFAULT_BOOT_ELECTION_TIMEOUT 5
616 
620 typedef enum {
624  CL_GMS_MEMBER_EJECT_REASON_UNKNOWN = 0,
629  CL_GMS_MEMBER_EJECT_REASON_API_REQUEST = 1
630 } ClGmsMemberEjectReasonT;
631 
636 ClRcT
637 clGmsSelectionObjectGet (
641  ClGmsHandleT clmHandle,
646  ClSelectionObjectT *pSelectionObject
647  );
648 
652 ClRcT
653 clGmsDispatch (
657  ClGmsHandleT clmHandle,
661  ClDispatchFlagsT dispatchFlags
662  );
663 
664 /*
665  * Funtion called by CPM when the event component comes up
666  */
667 ClRcT clGmsCompUpNotify (
668  ClUint32T compId);
669 
670 /******************************************************************************
671  * Callback Functions:
672  *****************************************************************************/
702 typedef void (*ClGmsClusterTrackCallbackT) (
703  CL_IN const ClGmsClusterNotificationBufferT *notificationBuffer,
704  CL_IN ClUint32T numberOfMembers,
705  CL_IN ClRcT rc);
706 
707 
733 typedef void (*ClGmsClusterMemberGetCallbackT) (
734  CL_IN ClInvocationT invocation,
735  CL_IN const ClGmsClusterMemberT *clusterMember,
736  CL_IN ClRcT rc);
737 
738 
769 typedef void (*ClGmsGroupTrackCallbackT) (
770  CL_IN ClGmsGroupIdT groupId,
771  CL_IN const ClGmsGroupNotificationBufferT *notificationBuffer,
772  CL_IN ClUint32T numberOfMembers,
773  CL_IN ClRcT rc);
774 
775 
801 typedef void (*ClGmsGroupMemberGetCallbackT) (
802  CL_IN ClInvocationT invocation,
803  CL_IN const ClGmsGroupMemberT *groupMember,
804  CL_IN ClRcT rc);
805 
806 
810 typedef struct ClGmsCallbacksT {
817  ClGmsClusterMemberGetCallbackT clGmsClusterMemberGetCallback;
818 
828  ClGmsClusterTrackCallbackT clGmsClusterTrackCallback;
829 
839  ClGmsGroupTrackCallbackT clGmsGroupTrackCallback;
840 
847  ClGmsGroupMemberGetCallbackT clGmsGroupMemberGetCallback;
848 } ClGmsCallbacksT;
849 
850 
851 /******************************************************************************
852  * API FUNCTION DECLARATIONS:
853  *****************************************************************************/
854 
898 extern ClRcT clGmsInitialize(
899  CL_OUT ClGmsHandleT *gmsHandle,
900  CL_IN const ClGmsCallbacksT *gmsCallbacks,
901  CL_INOUT ClVersionT *version);
902 
903 
942 extern ClRcT clGmsFinalize(
943  CL_IN ClGmsHandleT gmsHandle);
944 
986 extern ClRcT clGmsClusterTrack(
987  CL_IN ClGmsHandleT gmsHandle,
988  CL_IN ClUint8T trackFlags,
989  CL_INOUT ClGmsClusterNotificationBufferT *notificationBuffer);
990 
1015 extern ClRcT clGmsClusterTrackStop(
1016  CL_IN ClGmsHandleT gmsHandle);
1017 
1059 extern ClRcT clGmsClusterMemberGet(
1060  CL_IN ClGmsHandleT gmsHandle,
1061  CL_IN ClGmsNodeIdT nodeId,
1062  CL_IN ClTimeT timeout,
1063  CL_OUT ClGmsClusterMemberT *clusterMember);
1064 
1103 extern ClRcT clGmsClusterMemberGetAsync(
1104  CL_IN ClGmsHandleT gmsHandle,
1105  CL_IN ClInvocationT invocation,
1106  CL_IN ClGmsNodeIdT nodeId);
1107 
1108 
1109 #ifdef __cplusplus
1110 }
1111 #endif
1112 
1113 #endif /* _CL_CLM_TMS_COMMON_H */
1114 
1115 
Generated on Tue Jan 10 10:29:15 PST 2012 for OpenClovis SDK using Doxygen