Group Services Programming Guide and Reference

ha_gs_vote subroutine

Purpose

ha_gs_vote - Called by a provider of a group to submit its vote on a proposal during a voting phase of an executing protocol

Library

GSAPI Thread-Safe Library (libha_gs_r.a)

GSAPI Library (not thread-safe) (libha_gs.a)

Syntax

#include <ha_gs.h>
 
ha_gs_rc_t
    ha_gs_vote  (
                ha_gs_token_t               provider_token,
                ha_gs_vote_value_t          vote_value,
        const   ha_gs_state_value_t         *proposed_state_value,
        const   ha_gs_provider_message_t    *provider_message,
                ha_gs_vote_value_t          default_vote_value)
 

Parameters

provider_token

A token that identifies the caller as a provider of the group. This token was previously initialized when the provider joined the group using the ha_gs_join subroutine.

vote_value

A field that contains the value of the vote. It can take one of the following values:

HA_GS_VOTE_APPROVE

Approve the proposal.

HA_GS_VOTE_CONTINUE

Neither approve nor reject the proposal right now, but propose another voting phase (continue to another voting phase).

HA_GS_VOTE_REJECT

Reject the proposal.

proposed_state_value

An optional updated state value for the group. If the provider does not wish to propose an updated state value, specify a null pointer.

For information on the definition of a group's state value, see the ha_gs_change_state_value man page.

provider_message

An optional provider-broadcast message to be sent to the providers as part of the next notification for this protocol. If the provider does not wish to send a message, specify a null pointer. For information on the definition of this message, see the ha_gs_send_message man page.

default_vote_value

The default vote value to be used by the group if any provider fails to vote during this phase. It can take one of the following values:

HA_GS_NULL_VOTE

A null vote. This value keeps the default vote at its previous value.

HA_GS_VOTE_APPROVE

Approve the proposal.

HA_GS_VOTE_REJECT

Reject the proposal.

Description

The ha_gs_vote subroutine is used by a provider of a Group Services group to submit its vote on a proposal during a voting phase of an executing protocol.

When an application has selected an n-phase protocol, providers will be expected to vote on proposed changes to the group. A change in either the group's state or its membership may be voted on. When a vote is requested, the appropriate callback routine is called for each of the providers, and each of the providers is expected to return a vote using this subroutine within the time limit previously established by the group.

This subroutine operates synchronously.

Voting results are tallied as follows:

• If all providers vote to APPROVE the proposal in the same voting phase, the protocol is approved.
• If any one provider votes to CONTINUE to another voting phase, the protocol proceeds to another voting phase.
• If any one provider votes to REJECT the proposal, the protocol is rejected and ends, regardless of any other votes.

Default votes are applied as if they were specified by the providers,

except in the case of failure leave protocols.

If multiple providers, in the same voting phase, submit state value changes or provider messages, the Group Services subsystem chooses only one of each. Therefore, if different providers submit different values, it is arbitrary which values the Group Services subsystem will choose.

• If all providers submit the same values, then it does not matter which values are chosen.
• If only one provider submits values (that is, all of the other providers submit null values), then the Group Services subsystem chooses that provider's submission.
• If different providers can submit different values, they must be prepared to see other values chosen.

Restrictions

The calling process must be a provider. The group must be running an n-phase protocol.

Return Values

If the ha_gs_vote subroutine is successful, it returns a value of 0 (HA_GS_OK).

Error Values

If the ha_gs_vote subroutine is unsuccessful, it returns an error number synchronously.

The GSAPI error numbers are defined in the ha_gs.h header file. For more information on GSAPI errors, see GSAPI errors (err_gsapi).

Synchronous Errors

The following errors may be returned synchronously by the ha_gs_vote subroutine:

HA_GS_BAD_MEMBER_TOKEN

The given provider_token does not specify a valid provider joined to a group.

HA_GS_NO_INIT

The GS client has not yet successfully initialized itself with Group Services by calling ha_gs_init().

HA_GS_BAD_PARAMETER

The given vote value is invalid (it must be one of HA_GS_VOTE_APPROVE, HA_GS_VOTE_CONTINUE, or HA_GS_VOTE_REJECT); or the given default vote value is invalid (it must be one of HA_GS_NULL_VOTE, HA_GS_VOTE_APPROVE, or HA_GS_VOTE_REJECT).

HA_GS_NOT_OK

The connection to the GS daemon has been lost. The GS client needs to reinitialize (via ha_gs_init()).

HA_GS_VOTE_NOT_EXPECTED

The group to which this provider is joined is not currently running a protocol.

Asynchronous Errors

None.

Files

ha_gs.h

Prerequisite Information

Understanding Group Services.

Related Information

Subroutines: ha_gs_join, ha_gs_change_state_value, ha_gs_send_message, ha_gs_change_attributes, ha_gs_goodbye