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
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:
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:
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:
The given parameter must be HA_GS_BLOCKING or HA_GS_NON_BLOCKING.
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
Related Information
Subroutine: ha_gs_init