Sun Microsystems Logo
Products and Services
 
Support and Training
 
 

A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X  Y  Z  
 
Program Interfacecmm_cmc_register(3CMM)


NAME

 cmm_cmc_register, cmm_cmc_unregister - register to receive notifications; remove registration and stop receiving notifications

SYNOPSIS

 
cc [ flag... ] file...  -lcgha_cmm  -lrt
 
#include <cmm.h>
 
typedef struct {
    cmm_cmchanges_t	cmchange;
    cmm_nodeid_t nodeid;
} cmm_cmc_notification_t;
 
typedef void (*cmm_notify_t) 
    (const cmm_cmc_notification_t *change_notification, 
     void *client_data);
cmm_error_t cmm_cmc_register(cmm_notify_t const callback, void * client_data);
cmm_error_t cmm_cmc_unregister ( );

DESCRIPTION

The cmm_cmc_register() function enables a system service or application to receive change notifications by registering the callback function indicated.

PARAMETERS

The cmm_cmc_register() function takes the following parameters:

callback

A pointer to a callback function defined by the service or application.

client_data

A parameter used by the callback function. Its type and value are defined by the registered service or application. It is passed as an argument to the callback and it is valid in the calling process address space. No sanity check is run on this parameter, as nhcmmd(1M) does not know its meaning.

EXTENDED DESCRIPTION

If the cmm_cmc_register() function is called while a callback is registered, a CMM_EEXIST error is returned because only one function can be registered at a time. To change the registration, cmm_cmc_unregister() must be called prior to registering the new node with cmm_cmc_register().

Registration only needs to be done once to receive cluster membership change notifications. When a process attempts to register more than once, the first callback is kept and an error is returned.

The calling process must use the cmm_notify_getfd(3CMM) and cmm_notify_dispatch(3CMM) functions to receive and dispatch messages from nhcmmd(1M). An application defines the list of notifications it receives by calling cmm_cmc_filter(3CMM).

Note that the order of callback notifications is the same as that of the Cluster Membership Manager (CMM) notifications; one call to cmm_notify_dispatch(3CMM) can lead to several calls to the callback (in fact as many as the number of pending notifications). Within these callbacks, if functions are invoked concerning the state of the cluster (for instance to get the number of nodes in the cluster), the results of the functions do not refer to the state that the cluster is in when the notification has been generated. Instead, the results of the functions refer to the state of the cluster when the function is invoked. In the meantime, some other modifications might have occurred in the cluster.

The callback function is invoked by the same thread as the one that calls the cmm_notify_dispatch(3CMM) function. The function is invoked by a library linked to the process. The library communicates with the CMM API that supplies the membership change information passed as an argument to the callback function.

The cmm_cmc_unregister() function removes the calling process's registration so that no further delivery of cluster membership change notifications is made. Only the process on which a callback is called can remove the caller's registration. A child or a parent process cannot do this.

If the calling process callback function is active when the unregister request is made, it is not canceled.

In case of fork(), the created child process does not inherit the registration from its parent. It has to make its own registration.

RETURN VALUES

The cmm_cmc_register() function returns one of the following values:

CMM_EBUSY

The CMM API server is temporarily out of resources to respond to the requested operation. The recommended action is to wait a short time and retry the operation. The length of the waiting must be decided by the user, depending on the application's characteristics.

CMM_ECONN

No nhcmmd is currently accessible on the local node.

CMM_ENOENT

The maximum number of clients that can register with cmm_cmc_register() at any one time has been reached.

CMM_EEXIST

The calling process has already registered a callback.

CMM_ENOTSUP

Unexpected service error. The cluster might be in a critical state.

CMM_ETIMEDOUT

The call timeout expired before the action was completed.

CMM_OK

Operation succeeds.

The cmm_cmc_unregister() function returns one of the following values:

CMM_EBUSY

The CMM API server is temporarily out of resources to respond to the requested operation. The recommended action is to wait a short time and retry the operation. The length of the waiting must be decided by the user, depending on the application's characteristics.

Another possible meaning of CMM_EBUSY is that a call is made to the cmm_cmc_unregister() function when the calling process's callback function is active.

CMM_ECONN

There is no nhcmmd currently accessible on the local node.

CMM_ENOENT

The registration does not exist.

CMM_ENOTSUP

Unexpected service error. The cluster might be in a critical state.

CMM_ETIMEDOUT

The call timeout expired before the action was completed.

CMM_OK

Operation succeeds.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPEATTRIBUTE VALUE
ArchitectureSPARC
AvailabilitySUNWnhcmd
Interface StabilityEvolving
MT-LevelMT-Safe
Cancel-SafetyDeferred-Cancel-Safe Asynchronous-Cancel-Unsafe

SEE ALSO

nhcmmd(1M), fork(2), cmm_cmc_filter(3CMM), cmm_notify_dispatch(3CMM), cmm_notify_getfd(3CMM)


Netra HAS FS 2.1Go To TopLast Changed September 2004