Purpose
ha_gs_leave - Called by a provider of a group to leave the group voluntarily
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_leave(
ha_gs_token_t provider_token,
const ha_gs_proposal_info_t *proposal_info)
Parameters
Description
The ha_gs_leave subroutine is used by a provider of a Group Services group to leave the group.
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 leave request is supplied through the leave request block, which is a type of proposal information block. On the ha_gs_leave subroutine, specify the proposal information block as a leave request block. For the definition of the proposal information block, see the ha_gs_delayed_error_callback man page.
The leave request block has the following definition:
typedef struct {
ha_gs_num_phases_t gs_num_phases;
ha_gs_time_limit_t gs_time_limit;
unsigned int gs_leave_code;
} ha_gs_leave_request_t;
The gs_num_phases field specifies whether the leave protocols are to be n-phase or one-phase protocols. It can take one of the following values:
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_leave_code field contains a four-byte value that is defined by the application using the GSAPI, and is controlled by the providers in a way that is meaningful to the application. When a provider leaves a group, the leave code is passed to the other providers with the leave protocol notification. Leave codes are not interpreted by the Group Services subsystem.
Restrictions
The calling process must be a provider.
Return Values
If the ha_gs_leave 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.
Once a voluntary leave protocol is started within the group by the Group Services subsystem, the provider who proposed the leave will receive only the first notification of the protocol. The first notification is the n-phase notification of an n-phase protocol, or the approved notification of a one-phase protocol. After this point, this provider is removed from the group and receives no more notifications. Even if the protocol is rejected, the provider is still removed from the group.
Error Values
If the ha_gs_leave 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_leave subroutine:
Asynchronous Errors
The following errors may be returned asynchronously by the ha_gs_leave subroutine:
Files
ha_gs.h
Prerequisite Information
Related Information
Subroutines: ha_gs_init, ha_gs_join, ha_gs_change_state_value, ha_gs_send_message, ha_gs_subscribe, ha_gs_expel, ha_gs_change_attributes, ha_gs_goodbye