Purpose
ha_gs_expel - Called by a provider of a group to request the expulsion of one or more providers.
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_expel(
ha_gs_token_t provider_token,
const ha_gs_proposal_info_t *proposal_info)
Parameters
Description
The ha_gs_expel subroutine is used by a provider of a Group Services group to propose the expulsion of one or more providers. A provider may propose the expulsion of itself.
A group might decide that a provider should be expelled for a number of reasons. Examples include:
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 expel request is supplied through the expel request block, which is a type of proposal information block. On the ha_gs_expel subroutine, specify the proposal information block as an expel request block. For the definition of the proposal information block, see the ha_gs_delayed_error_callback man page.
The expel 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_membership_t gs_expel_list;
unsigned int gs_deactivate_phase;
char *gs_deactivate_flag;
} ha_gs_expel_request_t;
The gs_num_phases field specifies whether the expel protocols are to be n-phase protocols 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.
For providers that are not being expelled, 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.
For providers that are being expelled, this is the number of seconds within which the deactivate script must complete. Otherwise, the deactivate script is considered unsuccessful. The deactivate script that is invoked is the one that was specified on the ha_gs_init subroutine when the provider that is being expelled first registered with Group Services.
The gs_expel_list field is a list of providers that are targeted to be expelled. It has the following definition:
typedef struct {
unsigned int gs_count;
ha_gs_provider_t *gs_providers;
} ha_gs_membership_t;
The gs_count field contains the number of providers in the list.
The gs_providers field points to the list of providers. Each provider is described by a provider information block, which is defined in the ha_gs_n_phase_callback man page.
The providers in the expel list do not take part in the protocol and receive no notice of it, unless it is approved.
All of the providers that are not targeted for expulsion take part in the protocol, even if they were declared nonresponsive before the protocol began.
The gs_deactivate_phase field contains the phase number in which the deactivate script should be run against the providers that are being expelled. If this field contains 0, no deactivate script will be invoked.
The gs_deactivate_flag field contains a flag that is to be passed to the deactivate script. It is a pointer to a null-terminated string with a maximum length of 256 bytes. If you specify a string that is longer than 256 bytes, it will be truncated. If the pointer is null, no flag will be passed to the deactivate script.
Deactivate Scripts
For information about deactivate scripts, see Deactivate scripts.
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_expel 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_expel 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).
Asynchronous Errors
The following errors may be returned asynchronously by the ha_gs_expel subroutine:
Synchronous Errors
The following errors may be returned synchronously by the ha_gs_expel 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_change_attributes, ha_gs_goodbye