sun.com | docs.sun.com |  | How To Buy | My Sun | Worldwide Sites |

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 Interface | cmm_cmc_register(3CMM)

- NAME
- SYNOPSIS
- DESCRIPTION
- PARAMETERS
- EXTENDED DESCRIPTION
- RETURN VALUES
- ATTRIBUTES
- SEE ALSO

## 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 TYPE | ATTRIBUTE VALUE
> --- | ---
> Architecture | SPARC
> Availability | SUNWnhcmd
> Interface Stability | Evolving
> MT-Level | MT-Safe
> Cancel-Safety | Deferred-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.1 | Go To Top | Last Changed September 2004

Company Info | Contact | Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.