Group Services Programming Guide and Reference

ha_gs_change_state_value subroutine

Purpose

ha_gs_change_state_value - Called by a provider of a group to propose a change to the group's state value

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_change_state_value(
                ha_gs_token_t           provider_token,
        const   ha_gs_proposal_info_t   *proposal_info)
 

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.

proposal_info

A pointer to a buffer that contains a proposal information block, which describes the proposed state change request.

Description

The ha_gs_change_state_value subroutine is used by a provider of a Group Services group to propose a change to the group's state value.

If the request is specified as a one-phase protocol, and Group Services chooses to run this protocol, the group's providers are notified using normal protocol approval procedures.

If the request is specified as an n-phase protocol, and Group Services chooses to run this protocol, the group's providers are notified using normal n-phase voting procedures.

If the Group Services subsystem chooses not to run this protocol (because another protocol is already in progress), the HA_GS_COLLIDE error number is returned either synchronously or asynchronously, depending on when the error is detected. Asynchronous errors are delivered through the delayed error callback routine. Otherwise, the proposal will initiate a protocol within the group.

Information about the state change request is supplied through the state change request block, which is a type of proposal information block. On the ha_gs_change_state_value subroutine, specify the proposal information block as a state change request block. For the definition of the proposal information block, see the ha_gs_delayed_error_callback man page.

The state change request block has the following definition:

typedef struct {
    ha_gs_num_phases_t      gs_num_phases;
    ha_gs_time_limit_t      gs_time_limit;
    ha_gs_state_value_t     *gs_new_state;
} ha_gs_state_change_request_t;

The gs_num_phases field specifies whether the state change protocols are to be n-phase protocols or one-phase protocols. It can take one of the following values:

HA_GS_1_PHASE

The protocols are to be one-phase protocols. One-phase protocols are automatically approved.

HA_GS_N_PHASE

The protocols are to be n-phase protocols, which put the group into multi-phase voting.

The gs_time_limit field contains the voting phase time limit, in seconds. This is the number of seconds within which each provider must register its vote for each phase of an n-phase protocol. If the field is set to a value of 0, no limit is enforced.

The gs_new_state field points to a buffer that contains the proposed new value for the group's state. The group state value has the following definition:

typedef  struct {
    int         gs_length;
    char        *gs_state;
} ha_gs_state_value_t;

The gs_length field contains the length, in bytes, of the state value. It must be a value between 1 and 256.

The gs_state field points to a buffer that contains the actual state value bytes. The state value of a group is defined by the application that is using the GSAPI. The state value is controlled by the providers in a way that is meaningful to the application. The state value is not interpreted by the Group Services subsystem.

Restrictions

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

Return Values

If the ha_gs_change_state_value subroutine is successful, it returns a value of 0 (HA_GS_OK). Group Services has accepted the request and will asynchronously attempt to run the proposed protocol.

Error Values

If the ha_gs_change_state_value subroutine is unsuccessful, it returns an error number. If the error is detected immediately, an error is returned synchronously. If the error is detected after the call has been accepted, an error is returned asynchronously.

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_change_state_value subroutine:

HA_GS_BAD_MEMBER_TOKEN

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

HA_GS_BAD_PARAMETER

The number of phases specified for the protocol is not allowable; it must be HA_GS_1_PHASE or HA_GS_N_PHASE.

HA_GS_COLLIDE

The provider's group is already running a protocol or this provider has already submitted a protocol request.

HA_GS_NO_INIT

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

HA_GS_NOT_A_MEMBER

The given provider_token does not specify a valid group.

HA_GS_NOT_OK

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

Asynchronous Errors

The following errors may be returned asynchronously by the ha_gs_change_state_value subroutine:

HA_GS_NOT_A_MEMBER

The provider that is proposing the protocol is no longer a provider for the specified group.

HA_GS_BAD_PARAMETER

The specified parameter was not valid.

HA_GS_COLLIDE

Another protocol is already active for this group.

Files

ha_gs.h

Prerequisite Information

Understanding Group Services.

Related Information

Subroutines: ha_gs_init, ha_gs_join, ha_gs_send_message, ha_gs_leave, ha_gs_expel, ha_gs_subscribe, ha_gs_change_attributes, ha_gs_goodbye