Group Services Programming Guide and Reference

ha_gs_goodbye subroutine

Purpose

ha_gs_goodbye - Called by a provider of a group to immediately leave the group

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_goodbye(ha_gs_token_t provider_token       

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.

Description

The ha_gs_goodbye() subroutine enables a provider to immediately leave its group as if it had failed, while informing the group that it "failed" voluntarily. This is a synchronous interface.

If this call returns with an HA_GS_OK return code, then the calling provider is no longer in the group.

If the group is in an n-phase protocol, the provider issuing the ha_gs_goodbye protocol is considered to have failed. The Group Services subsystem will apply the group's default vote for any subsequent voting phases in that protocol.

The result of a provider successfully issuing this call is that when the remaining providers in the group see this provider's failure protocol, the leave reason for this provider will be set to HA_GS_PROVIDER_SAID_GOODBYE. (See the discussion of gs_leave_info in the section about the ha_gs_n_phase_callback subroutine on page ***.)

Restrictions

The calling process must be a provider.

Return Values

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

Error Values

If the ha_gs_goodbye subroutine is unsuccessful, it returns an error number. If the error is detected immediately, an error is returned 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_goodbye subroutine:

HA_GS_BACKLEVEL_PROVIDERS

The group contains providers who were compiled against an older level of the GS library. They must leave the group before ha_gs_goodbye() can be used by this provider.

HA_GS_BAD_MEMBER_TOKEN

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

HA_GS_NOT_SUPPORTED

The GS client was not compiled against the proper level of the GS library to use this function.

HA_GS_NO_INIT

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

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

None.

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