Purpose
ha_gs_join - Called by a GS client to join a group as a provider
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_join(
ha_gs_token_t *provider_token,
const ha_gs_proposal_info_t *proposal_info)
Parameters
The GS client must pass a copy of the token on all subsequent GSAPI calls that refer to the group. The GSAPI passes a copy of the token to the GS client on all subsequent callbacks that refer to the group.
Description
The ha_gs_join subroutine is used by a GS client to join a group as a provider. If the named group does not already exist, it is created.
This section describes:
On input, information about the join request is supplied through the join request block, which is a type of proposal information block. On the ha_gs_join subroutine, specify the proposal information block as a join request block. For the definition of the proposal information block, see the ha_gs_delayed_error_callback man page.
The join request block has the following definition:
typedef struct {
ha_gs_group_attributes_t *gs_group_attributes;
short gs_provider_instance;
char *gs_provider_local_name;
ha_gs_n_phase_cb_t *gs_n_phase_protocol_callback;
ha_gs_approved_cb_t *gs_protocol_approved_callback;
ha_gs_rejected_cb_t *gs_protocol_rejected_callback;
ha_gs_announcement_cb_t *gs_announcement_callback;
ha_gs_merge_cb_t *gs_merge_callback;
} ha_gs_join_request_t;
The gs_group_attributes field contains a pointer to a group attributes block, which is described later in this section.
The gs_provider_instance field contains the instance number to be used by this provider. If it is not unique on this node for this group, the join is rejected asynchronously with an error number of HA_GS_DUPLICATE_INSTANCE_NUMBER.
The gs_provider_local_name field points to an optional byte string that contains a local "name" for the provider. The name is used only locally, when logging errors or messages related to the provider. The provider local name is not distributed to the other providers.
The gs_n_phase_protocol_callback field points to the callback routine that is to be called during each voting phase of any n-phase protocol.
The gs_protocol_approved_callback field points to the callback routine that is to be called when the Group Services subsystem has an announcement to deliver that a protocol (one-phase or n-phase) has been approved in this group.
The gs_protocol_rejected_callback field points to the callback routine that is to be called when the Group Services subsystem has an announcement to deliver that a protocol (one-phase or n-phase) has been rejected in this group.
The gs_announcement_callback field points to the callback routine that is to be called when the Group Services subsystem has other announcements to deliver that are related to this group.
All of the above fields that point to callback routines should point to valid functions. If a NULL pointer is given in any of them, a warning will be issued to the GS client's STDERR. If a pointer is NULL, or if it is not NULL but does not point to an executable function, unpredictable results (such as fatal program failure) may occur during execution of your program.
The gs_merge_callback field is reserved for IBM use. It should be set to NULL.
The group attributes block describes the attributes of the group, including the group's name, and is specified as input to a join request using the ha_gs_join subroutine. It has the following definition:
typedef char *ha_gs_group_name_t;
typedef struct {
short gs_version;
short gs_sizeof_group_attributes;
unsigned gs_client_version;
ha_gs_group_name_t gs_group_name;
ha_gs_batch_ctrl_t gs_batch_control;
ha_gs_num_phases_t gs_num_phases;
ha_gs_num_phases_t gs_source_reflection_num_phases;
ha_gs_vote_value_t gs_group_default_vote;
ha_gs_merge_ctrl_t gs_merge_control;
ha_gs_time_limit_t gs_time_limit;
ha_gs_time_limit_t gs_source_reflection_time_limit;
ha_gs_group_name_t gs_source_group_name;
} ha_gs_group_attributes_t;
The group attributes block contains the name of the group and the set of group attributes that are passed to the Group Services subsystem on the ha_gs_join subroutine call.
If the group does not already exist, a new group is defined with the specified attributes.
If the group already exists, the specified attributes must match the group's existing attributes. All of the attributes must match except those that are contained in the gs_version and gs_sizeof_group_attributes fields. Otherwise, the call fails with an error number of HA_GS_BAD_GROUP_ATTRIBUTES.
The gs_version field contains the version level of the Group Services library. It is set by the Group Services subsystem.
The gs_sizeof_group_attributes field contains the size of the group attributes block.
The gs_client_version field contains a user-defined version code.
The gs_group_name field points to a string that contains the name of the group. Its maximum length is 32 bytes, as defined by the HA_GS_MAX_GROUP_NAME_LENGTH constant.
The gs_batch_control field controls the batching of multiple group joins and failure leaves. Either alone may be batched, or both. A failure leave occurs when a provider process is forced to leave a group because the process, or the node on which it is running, fails.
The gs_batch_control field can take one of the following values:
The gs_num_phases field specifies whether join protocols and failure leave (including cast-out) protocols are to be n-phase protocols or one-phase protocols. It can take one of the following values:
The gs_source_reflection_num_phases field contains the number of phases for source-reflection protocols, which are run in the target-group when the source-group changes its state value. If no gs_source_group_name is given, this field is ignored.
The gs_source_reflection_num_phases field can take one of the following values:
The gs_group_default_vote field contains the default vote to use for the providers in this group. It can take on a value of HA_GS_VOTE_APPROVE to approve or HA_GS_VOTE_REJECT to reject.
The gs_merge_control field specifies how the merging of groups should be handled. It must be set to a value of HA_GS_DISSOLVE_MERGE.
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 join or failure leave protocol. If the field is set to a value of 0, no limit is enforced.
The gs_source_reflection_time_limit field contains the time limit, in seconds, for each voting phase of a source-reflection protocol. It is run in the target-group when the source-group changes its state value. If no gs_source_group_name is specified, or if it is specified and the gs_source_reflection_phases field contains a value of HA_GS_1_PHASE, this field is ignored.
The gs_source_group_name field points to a string that contains the name of the source-group for this group. If there is no source-group, this field should be null.
The ha_gs_join subroutine operates as follows.
First, it verifies that all of the required fields have been specified. If this checking succeeds, it submits a join request to initiate a join protocol within the specified group and returns synchronously with a successful return value (HA_GS_OK).
The join request is processed asynchronously. If errors are detected asynchronously, they are returned through the delayed error callback routine that was previously specified on the call to the ha_gs_init subroutine.
Upon receipt of the join request, Group Services checks the group attributes that were specified on input. If the named group already exists, it checks to see that the input group attributes match those that have already been established for the group. If they do not match, the HA_GS_BAD_GROUP_ATTRIBUTES error number is returned asynchronously by the delayed error callback routine.
If the join request is for a new group, Group Services uses the attributes specified on the join request to establishes the new group's attributes.
If the asynchronous checks succeed, Group Services initiates a membership change protocol within the group to enable the provider to join. Each provider in the group, including the joiner, is notified. The appropriate callback is invoked, based on the number of phases that are required for the join request.
Restrictions
The calling process must be a GS client.
Return Values
If the ha_gs_join subroutine is successful, it returns a value of 0 (HA_GS_OK) and the provider_token field is set to the token that identifies this provider's connection to the group.
Note that provider tokens are assigned, invalidated, and reassigned in a manner similar to the way in which file descriptors are assigned, invalidated, and reassigned as files are opened and closed.
Here is an example.
A GS client joins group foo and receives provider token 0. When the same client leaves group foo, Group Services invalidates provider token 0 and makes it available for reassignment. When the next GS client (it could be the same or a different GS client) joins the next group (it could be the same or a different group), Group Services assigns provider token 0 to that client.
If the ha_gs_join subroutine returns HA_GS_OK synchronously, that means only that the Group Services subsystem has accepted the join request. The GS client is not fully joined to the group as a provider until the join protocol has run and has been approved by the group.
Error Values
If the ha_gs_join subroutine is unsuccessful, it returns an error number. The contents of the provider_token field are undefined.
If either an asynchronous error is reported by the delayed error callback routine, or the join protocol is rejected by the group, the GS client is not a provider in the group and the provider token that was returned is not valid for any requests.
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_join subroutine:
Asynchronous Errors
The following errors may be returned asynchronously by the ha_gs_join subroutine:
Files
ha_gs.h
Prerequisite Information
Related Information
Subroutines: ha_gs_init, ha_gs_change_state_value, ha_gs_send_message, ha_gs_leave, ha_gs_expel, ha_gs_send_message, ha_gs_subscribe, ha_gs_change_attributes, ha_gs_goodbye