3.1.1.8 Notification Ports

  • Article

A notification port is a first-in, first-out queue containing indications that some portion of the volatile and/or nonvolatile cluster state has changed. A notification port is not part of the nonvolatile cluster state.

Notification ports have a version which is either 1 or 2, depending on whether the notification was created with a call to ApiCreateNotify (ClusAPI Protocol version 2, section 3.1.4.1.56 or ClusAPI Protocol version 3, section 3.1.4.2.56) or ApiCreateNotifyV2 (protocol version 3 section 3.1.4.2.136), respectively.

A version 1 event indication contains the following information:

  • A value from the CLUSTER_CHANGE (section 2.2.2.7) enumeration, as described in section 2.2.2.7, that indicates the type of event that has occurred.

  • The name of the object to which the event pertains.

  • For objects with state, a numerical value associated with the object's state.

  • A client-supplied context value.

A version 2 event indication contains the following information:

A notification port supports the registration of one or more filters that identify the types of event indications that are posted to the port. The filter is associated either with one or more cluster object classes or a specific cluster object and has an associated 32-bit integer context value that is supplied at registration; this value is returned with each indication that was queued to the port as a result of a match between the context value's filter and the event type.

Each version 1 indication includes a 32-bit integer value that is associated with the current state of the object; this value is supplied to various ClusAPI methods during the reconnection process, as specified in section 3.2.4.6. The state value is not part of the nonvolatile cluster state. The value is made consistent on all active nodes in the cluster through implementation-specific methods and protocols between servers.

A ClusAPI Protocol client can perform the following management operations on a version 1 cluster notification port (see section 4.3 for an example):

  • Create: Create a notification port for receiving information about changes in the cluster. For more information, see sections 3.1.4.1.56 (protocol version 2) and 3.1.4.2.56 (protocol version 3).

  • Close: Close the notification port. For more information, see sections 3.1.4.1.57 (protocol version 2), 3.1.4.2.57 (protocol version 3), 3.1.4.1.107 (protocol version 2), and 3.1.4.2.107 (protocol version 3).

  • Configure a notification port: Add a filter mask, a context value and/or objects of interest. For more information, see sections 3.1.4.1.58 through 3.1.4.1.65 (protocol version 2), sections 3.1.4.2.58 through 3.1.4.2.65 (protocol version 3), and sections 3.1.4.1.90 (protocol version 2), 3.1.4.1.91 (protocol version 2), 3.1.4.1.99 (protocol version 2), 3.1.4.1.100 (protocol version 2), 3.1.4.2.90 (protocol version 3), 3.1.4.2.91 (protocol version 3), 3.1.4.2.99 (protocol version 3), and 3.1.4.2.100 (protocol version 3).

  • Retrieve an event: Get the first event at the head of the queue. For more information, see sections 3.1.4.1.66 (protocol version 2) and 3.1.4.2.66 (protocol version 3).

A ClusAPI Protocol client can perform the following management operations on a version 2 cluster notification port:

  • Create: Create a notification port for receiving information about changes in the cluster. For more information, see ApiCreateNotifyV2 (section 3.1.4.2.136).

  • Close: Close the notification port. For more information, see ApiCloseNotify (section 3.1.4.2.57) and ApiUnblockGetNotifyCall (section 3.1.4.2.107).

  • Configure a notification port: Add a filter mask, a context value and/or objects of interest. For more information, see ApiAddNotifyV2 (section 3.1.4.2.137).

  • Retrieve an event: Get the events at the head of the queue. For more information, see ApiGetNotifyV2 (section 3.1.4.2.138).