IBM Books

Group Services Programming Guide and Reference

ha_gs_dispatch subroutine

Purpose

ha_gs_dispatch - Called by a GS client to handle messages that have arrived from the Group Services Application Programming Interface (GSAPI)

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_dispatch(
        const   ha_gs_dispatch_flag_t   dispatch_flags)
 

Parameters

dispatch_flags
A flag that indicates how messages from the Group Services Application Programming Interface (GSAPI) are to be processed. It can be one of the following values:

HA_GS_NON_BLOCKING
The GSAPI should check for messages that have arrived on the GSAPI socket. If any messages have arrived, the GSAPI should call the appropriate callback routines. If no messages have arrived, the GSAPI should return control immediately.

HA_GS_BLOCKING
The GSAPI should check for messages that have arrived on the GSAPI socket. As messages arrive, the GSAPI will call the appropriate callback routines, and it will continue to do so until an error occurs or the connection is broken.

Description

The ha_gs_dispatch subroutine is used by a process to handle messages from the Group Services Application Programming Interface (GSAPI). It is vital that the GS client calls this subroutine on a regular basis to be able to receive messages from the GSAPI for delivery as notifications by invoking the appropriate callback routines. This allows the GS client to respond to any protocols that may be running in the group. The parameter to this routine controls the behavior of ha_gs_dispatch once all outstanding messages have been delivered.

Although ha_gs_dispatch needs to be called regularly, exactly how often it is necessary will differ for each GS client. The most important factor is that the GS client should be ready to respond to arriving messages as quickly as possible. This allows it to respond to changes in its group or the system as quickly as possible. Once ha_gs_dispatch is called, it will process all messages that have arrived, which may result in multiple GS client callback routines being invoked. The dispatch_flags parameter controls the behavior of ha_gs_dispatch once all messages have been processed.

To assist in this, there are two general models of execution for a GS client. The different settings for the dispatch_flags parameter to ha_gs_dispatch correlate to these:

  1. The first model can be loosely described as the "non-blocking" model. This matches to the flag HA_GS_NON_BLOCKING, and is most appropriate to singly-threaded (or non-threaded) GS clients. In this model, it is expected that the GS client will remain responsive to arriving messages by using one of the following mechanisms:
    1. The system subroutine select(). In this case, the GS client should set up a select mask containing the file descriptor returned during the ha_gs_init subroutine in the ha_gs_descriptor field. When select() indicates that a message has arrived on this file descriptor from Group Services, the GS client should run ha_gs_dispatch with the HA_GS_NON_BLOCKING flag.
    2. Although it is not recommended, the GS client may set a fixed timer and simply call ha_gs_dispatch after some fixed time interval. This is not recommended. This is because the call may be more frequent than is necessary, and in most cases will result in no actions being taken because no messages have arrived. This may also cause the GS client to be very slow to respond to messages if the time period is too long, or if a number of messages arrive quickly.
  2. The second model is, alternately, a "blocking" model, and is indicated with the HA_GS_BLOCKING flag. This model is normally just appropriate to multi-threaded GS clients, although it may be used by singly-threaded (or non-threaded) GS clients.

    The HA_GS_BLOCKING flag causes all threads that enter ha_gs_dispatch to never return from ha_gs_dispatch, unless they encounter an error. In this case, they will return from ha_gs_dispatch with an HA_GS_NOT_OK return code. These threads simply remain in ha_gs_dispatch. As soon as a message arrives from Group Services, a thread will read the message and run the appropriate callback function.

    If the GS client has multiple threads call ha_gs_dispatch, all of these threads will queue up to read messages as they arrive in Group Services. The GSAPI library will handle synchronization of these threads to assure that they properly read and process messages. The GS client need only have as many threads as desired call ha_gs_dispatch with the HA_GS_BLOCKING flag.

A multi-threaded GS client may certainly use the non-blocking model described above, using select() or signals as desired. In this case, it is still valid for multiple threads to run ha_gs_dispatch. If a thread calls ha_gs_dispatch with the HA_GS_NON_BLOCKING flag and there are no pending messages to process, it will return from ha_gs_dispatch with an HA_GS_OK return code.

A key concern for multi-threaded GS clients is in dealing with parallel execution of callback functions. Since it is possible for a single GS client process to join multiple groups, subscribe to multiple groups, or both, the GSAPI library will enforce the following synchronization rules:

  1. There will never be more than one active callback function being invoked for any one group in parallel.
  2. However, where appropriate, callback functions for different groups will be invoked in parallel if there are multiple threads that have run ha_gs_dispatch and messages have arrived at the GS client for the different groups.

This leads to a general rule that a multi-threaded GS client that deals with multiple groups should be prepared to dedicate the same number of threads to ha_gs_dispatch as the number of groups with which the GS client is concerned. This keeps such a GS client as responsive as possible for all of its groups.

A singly-threaded (or non-threaded) GS client may also deal with multiple groups, although it will only be able invoke a single callback function at any one time. This may keep it from being able to be more responsive if messages arrive for multiple groups within a small amount of time.

A limitation for threaded GS clients is that any thread that has run ha_gs_dispatch should never be cancelled (via the pthread_cancel subroutine) or killed (via the pthread_kill subroutine) until after the thread has returned from ha_gs_dispatch. The behavior of the client will be unpredictable if such a thread is killed or cancelled.

A multi-threaded client must issue ha_gs_quit to disconnect from Group Services, and it must then wait for any threads that had invoked ha_gs_dispatch to return before they can be killed or cancelled.

Restrictions

The caller must be a GS client.

Return Values

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

Error Values

If the ha_gs_dispatch subroutine is unsuccessful, it returns an error number 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_dispatch subroutine:

HA_GS_BAD_PARAMETER

The given parameter must be HA_GS_BLOCKING or HA_GS_NON_BLOCKING.

HA_GS_NOT_OK

The connection to the GS daemon has been lost, or user authentication has failed. The GS client needs to reinitialize (via ha_gs_init()).

Asynchronous Errors

None.

Files

ha_gs.h

Prerequisite Information

Understanding Group Services.

Related Information

Subroutine: ha_gs_init


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]