Purpose
ha_gs_subscriber_callback - A callback routine that the Group Services subsystem calls to deliver a subscription notification to a GS client
Library
GSAPI Thread-Safe Library (libha_gs_r.a)
GSAPI Library (not thread-safe) (libha_gs.a)
Syntax
#include <ha_gs.h>
void
ha_gs_subscriber_callback(
const ha_gs_subscription_notification_t *notification)
Parameters
Description
The ha_gs_subscriber_callback subroutine defines a GS client's subscriber callback routine. The GS client uses it to handle subscription notifications from the Group Services subsystem. The process provides the address of the subscriber callback routine to the Group Services subsystem on the ha_gs_subscribe subroutine when it joins the group as a subscriber. The Group Services subsystem then calls the subscriber callback routine when it has a subscription notification to deliver to the GS client. A subscription notification is delivered when a protocol is approved in a group to which the process is subscribed and the protocol modifies the group's membership or state value.
If the gs_subscription_type field has a value of HA_GS_SUBSCRIPTION_DISSOLVED, the subscriber's connection to the Group Services subsystem will be closed as soon as the subscriber callback routine returns.
On input, the subscriber callback routine receives a pointer to the subscription notification block. The subscription notification block has the following definition:
typedef struct {
ha_gs_notification_type_t gs_notification_type;
ha_gs_token_t gs_subscriber_token;
ha_gs_subscription_type_t gs_subscription_type;
ha_gs_state_value_t *gs_state_value;
ha_gs_membership_t *gs_full_membership;
ha_gs_membership_t *gs_changing_membership;
ha_gs_special_data_t *gs_subscription_special_data;
} ha_gs_subscription_notification_t;
The gs_notification_type field contains the type of notification. For a subscription notification, it contains a value of HA_GS_SUBSCRIPTION_NOTIFICATION.
The gs_subscriber_token field contains a token that identifies the caller as a subscriber of the group. This token was previously initialized when the subscriber joined the group using the ha_gs_subscribe subroutine. If the gs_subscription_type field has a value of HA_GS_SUBSCRIPTION_DISSOLVED, this token no longer specifies a valid subscription.
The gs_subscription_type field contains one or more flags that indicate the type of change for which this subscription notification is being delivered. It can contain one or more of the following flags:
Joining and leaving providers are not listed together in a single notification. Therefore, no notification will contain both the HA_GS_SUBSCRIPTION_DELTA_JOIN and HA_GS_SUBSCRIPTION_DELTA_LEAVE flags.
Joining and leaving providers are not listed together in a single notification. Therefore, no notification will contain both the HA_GS_SUBSCRIPTION_DELTA_JOIN and HA_GS_SUBSCRIPTION_DELTA_LEAVE flags.
The subscription is deactivated. To start receiving notifications again, the subscriber must resubscribe to the group. If the group does not exist because providers have not rejoined it, each subscription request receives an asynchronous error code of HA_GS_UNKNOWN_GROUP.
The subscription is deactivated and the subscriber's connection to the Group Services daemon is terminated. Before calling any Group Services subroutines, the (former) subscriber must wait until control returns from the ha_gs_dispatch subroutine. Failure to do so may result in an application hang.
After the ha_gs_dispatch subroutine returns, the former subscriber must reinitialize the connection to Group Services by calling the ha_gs_init subroutine, and then take any other necessary actions to re-subscribe to the group.
If the HA_GS_SUBSCRIPTION_STATE flag is set in the gs_subscription_type field, the gs_state_value field points to a buffer that contains the new value for the group's state. For the definition of the group state value, see the ha_gs_change_state_value man page.
If the HA_GS_SUBSCRIBE_MEMBERSHIP flag is set in the gs_subscription_type field, the gs_full_membership field points to the full updated list of providers that currently belong to the group. 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.
If the HA_GS_SUBSCRIBE_DELTA_JOIN or HA_GS_SUBSCRIBE_DELTA_LEAVE flag is set in the gs_subscription_type field, the gs_changing_membership field points to the list of changing (either joining or leaving) providers rather than the full membership list. The membership list 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 gs_subscription_special_data field contains the special group-specific subscription data; it is valued only if gs_subscription_type has HA_GS_SUBSCRIPTION_SPECIAL_DATA set on.
For more details, see Appendix A, Subscription special data.
Restrictions
For important information about multiprocessing considerations that apply to all callback routines, see the ha_gs_n_phase_callback man page.
Return Values
None.
Error Values
None.
Synchronous Errors
None.
Asynchronous Errors
None.
Files
ha_gs.h
Prerequisite Information
Related Information
Subroutines: ha_gs_init, ha_gs_subscribe