clClmApi.h

Go to the documentation of this file.

/*
 * Copyright (C) 2002-2012 OpenClovis Solutions Inc.  All Rights Reserved.
 *
 * This file is available  under  a  commercial  license  from  the
 * copyright  holder or the GNU General Public License Version 2.0.
 * 
 * The source code for  this program is not published  or otherwise 
 * divested of  its trade secrets, irrespective  of  what  has been 
 * deposited with the U.S. Copyright office.
 * 
 * This program is distributed in the  hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied  warranty  of 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
 * General Public License for more details.
 * 
 * For more  information, see  the file  COPYING provided with this
 * material.
 */
/*******************************************************************************
 * ModuleName  : gms
 * File        : clGmsApi.h
 *******************************************************************************/

/*******************************************************************************
 * Description :
 * This client function implements the SA Forum compliant cluster membership
 * management.
 *
 * Component Manager (CPM) uses these functions to manage its node in the cluster.
 * This service assumes that there is only one cluster in the system.
 * 
 * An instance of this service (instantiated by the clGmsInitialize()
 * function and identified by the gmsHandle) can view and manage the cluster. 
 * If a node joins/leaves/kicked out of the cluster then all the other nodes 
 * in the cluster and its group components are updated with the current status.
 *  
 *********************************************************************************/

/*********************************************************************************/
/****************************** Group Management Service**************************/
/*********************************************************************************/
/*                                                                               */ 
/*  clGmsClusterJoin                                                             */
/*  clGmsClusterJoinAsync                                                        */
/*  clGmsClusterLeave                                                            */
/*  clGmsClusterLeaveAsync                                                       */
/*  clGmsClusterLeaderElect                                                      */
/*  clGmsClusterMemberEject                                                      */
/*                                                                               */
/**********************************************************************************/

#ifndef _CL_GMS_API_H
#define _CL_GMS_API_H

# ifdef __cplusplus
extern "C" {
# endif

#include <clCommon.h>
#include <clClmTmsCommon.h>

/*=========================================================================
 * Callback Functions:
 *=======================================================================*/

typedef void (*ClGmsClusterMemberEjectCallbackT) (
         CL_IN ClGmsMemberEjectReasonT   reasonCode);

typedef struct {

        ClGmsClusterMemberEjectCallbackT clGmsMemberEjectCallback;

} ClGmsClusterManageCallbacksT;

typedef ClRcT (*ClGmsLeaderElectionAlgorithmT)(
        ClGmsClusterNotificationBufferT buffer,
        ClGmsNodeIdT            *leaderNodeId,
        ClGmsNodeIdT            *deputyNodeId, 
        ClGmsClusterMemberT     *memberJoinedOrLeft,
        ClGmsGroupChangesT       cond 
        );


/*=========================================================================
 * API Functions:
 *=======================================================================*/

/*
 ************************************
 *  \brief Joins the cluster as a member. 
 * 
 *  \par Header File:
 *  clGmsApi.h
 *
 *  \param gmsHandle The handle, obtained through the clGmsInitialize() function,
 *   designating this particular initialization of the Group Membership Service.
 *  \param clusterManageCallbacks Callbacks for managing the cluster. 
 *  \param credentials This is an integer value specifying the
 *  leadership credibility of the node. Larger the value higher is the
 *  possibility of the node becoming a leader. Member with creditials
 *  \c CL_GMS_INELIGIBLE_CREDENTIALS cannot participate in the leader election.
 *  \param timeout If the cluster join is not completed within this time, 
 *  then the join request is timed out. 
 *  \param nodeId Node ID of the member that will join the cluster. 
 *  \param nodeName Name of the node that will join the cluster. 
 *
 *
 *  \retval CL_ERR_INVALID_HANDLE If the handle passed to the function is not valid.
 *  The handle passed should have been obtained from the clGmsInitialize() function.
 *  \retval CL_ERR_TIMEOUT If the join request timed out.
 *  \retval CL_ERR_INVALID_PARAMETER If any of the input parameters are invalid.
 *  \retval CL_ERR_NULL_POINTER If either of the parameters \e clusterManageCallbacks
 *  or \e nodeName are NULL.
 *  \retval CL_ERR_TRY_AGAIN: GMS server is not ready to process the request.

 *
 *  \par Description:
 *  This function is used to include a node into the the cluster as a member.
 *  Success  or failure is reported  via return value  
 *  Members who have registered for tracking, get notified by tracking callback.
 *
 *  \par Library File:
 *  ClGms
 *
 *  \sa clGmsClusterLeave()
 *
 */
extern ClRcT clGmsClusterJoin(
        CL_IN const ClGmsHandleT                        gmsHandle,
        CL_IN const ClGmsClusterManageCallbacksT* const clusterManageCallbacks,
        CL_IN const ClGmsLeadershipCredentialsT         credentials,
        CL_IN const ClTimeT                             timeout,
        CL_IN const ClGmsNodeIdT                        nodeId,
        CL_IN const ClNameT*                      const nodeName);


/*
 ************************************
 *  \brief Asynchronously joins the cluster as a member. 
 * 
 *  \par Header File:
 *  clGmsApi.h
 *
 *  \param gmsHandle The handle, obtained through the clGmsInitialize() function,
 *   designating this particular initialization of the Group Membership Service 
 *  \param clusterManageCallbacks Callbacks for managing the cluster. 
 *  \param credentials This is an integer value specifying the
 *  leadership credibility of the node. Larger the value higher is the
 *  possibility of the node becoming a leader. Member with creditials
 *  \c CL_GMS_INELIGIBLE_CREDENTIALS cannot participate in the leader election.
 *  \param timeout If the cluster join is not completed within this time, 
 *  then the join request is timed out. 
 *  \param nodeId Node ID of the member that will join the cluster. 
 *  \param nodeName Name of the node that will join the cluster.
 *
 *
 *  \retval CL_ERR_INVALID_HANDLE If the handle passed to the function is not valid.
 *  The handle passed should have been obtained from the clGmsInitialize() function.
 *  \retval CL_GMS_ERR_JOIN_DENIED If the node is already part of the cluster.
 *  \retval CL_ERR_INVALID_PARAMETER If any of the input parameters are invalid.
 *  \retval CL_ERR_NULL_POINTER If either of the parameters \e clusterManageCallbacks
 *  or \e nodeName are NULL.
 *
 *  \par Description:
 *  This function is used to asynchronously include a node into the cluster as a member.
 *  Success is reported via return value. 
 *  Members that have registered for tracking get notified by tracking
 *  callback.
 *
 *  \par Library File:
 *  ClGms
 * 
 *  \sa clGmsClusterJoin()
 *
 */
extern ClRcT clGmsClusterJoinAsync(
        CL_IN const ClGmsHandleT                         gmsHandle,
        CL_IN const ClGmsClusterManageCallbacksT*  const clusterManageCallbacks,
        CL_IN const ClGmsLeadershipCredentialsT          credentials,
        CL_IN const ClGmsNodeIdT                         nodeId,
        CL_IN const ClNameT*                       const nodeName);


/*
 ************************************
 *  \brief Leaves the cluster.  
 * 
 *  \par Header File:
 *  clGmsApi.h
 *
 *  \param gmsHandle The handle, obtained through the clGmsInitialize() function,
 *   designating this particular initialization of the Group Membership Service 
 *  \param timeout If the cluster leave operation is not completed within this time, 
 *  then the leave request is timed out.
 *  \param nodeId Node ID of the member that is leaving the cluster.  
 *
 *  \retval CL_ERR_INVALID_HANDLE If the handle passed to the function is not valid.
 *  The handle passed should have been obtained from the clGmsInitialize() function..
 *  \retval CL_ERR_INVALID_PARAMETER If any of the input parameters are invalid.
 *
 *  \par Description:
 *  This function is used to make a node leave the cluster. Once the node leaves the cluster 
 *  and the groups/components will be expelled and
 *  a reason for expulsion will be returned through their
 *  callback functions.
 *
 *  \par Library File:
 *  ClGms
 * 
 *  \sa clGmsClusterJoin()
 *
 */
extern ClRcT clGmsClusterLeave(
        CL_IN ClGmsHandleT                      gmsHandle,
        CL_IN ClTimeT                           timeout,
        CL_IN ClGmsNodeIdT                      nodeId);

extern ClRcT clGmsClusterLeaveNative(
        CL_IN ClGmsHandleT                      gmsHandle,
        CL_IN ClTimeT                           timeout,
        CL_IN ClGmsNodeIdT                      nodeId);


/*
 ************************************
 *  \brief Leaves the cluster asynchronously.  
 * 
 *  \par Header File:
 *  clGmsApi.h
 *
 *  \param gmsHandle The handle, obtained through the clGmsInitialize() function,
 *   designating this particular initialization of the Group Membership Service
 *  \param nodeId  Node ID of the member to be ejected out.
 *
 *  \retval CL_ERR_INVALID_HANDLE If the handle passed to the function is not valid.
 *  The handle passed should have been obtained from the clGmsInitialize() function.
 *  \retval CL_ERR_INVALID_PARAMETER If any of the input parameters are invalid.
 *
 *  \par Description:
 *  This function is used to make a node leave the cluster asynchronously. Once the node leaves the cluster 
 *  and the groups/components will be expelled and
 *  a reason for expulsion will be returned through their
 *  callback functions.
 *
 *  \par Library File:
 *  ClGms
 * 
 *  \sa clGmsClusterLeave() 
 *
 */
extern ClRcT clGmsClusterLeaveAsync(
        CL_IN ClGmsHandleT                      gmsHandle,
        CL_IN ClGmsNodeIdT                      nodeId);


extern ClRcT clGmsClusterLeaderElect(
        CL_IN       ClGmsHandleT                      gmsHandle,
        CL_IN       ClGmsNodeIdT                      preferredLeader,
        CL_INOUT    ClGmsNodeIdT                     *leader,
        CL_INOUT    ClGmsNodeIdT                     *deputy,
        CL_INOUT    ClBoolT                          *leadershipChanged);



extern ClRcT clGmsClusterMemberEject(
        CL_IN ClGmsHandleT                      gmsHandle,
        CL_IN ClGmsNodeIdT                      nodeId,
        CL_IN ClGmsMemberEjectReasonT           reason);


#ifdef  __cplusplus
}
#endif

#endif  /* _CL_GMS_CLUSTER_MANAGE_API_H_ */