Documentation Home
MySQL NDB Cluster API Developer Guide
Download this Manual

2.3.16.27 Ndb::pollEvents()

Description.  This method waits for a GCP to complete. It is used to determine whether any events are available in the subscription queue.

This method waits for the next epoch, rather than the next GCP. See Section 2.3.21, “The NdbEventOperation Class”, for more information.

In NDB 7.4.3 and later, you can (and should) use pollEvents2() instead of this method.

Prior to NDB 7.4.7, pollEvents() was not compatible with the exceptional TableEvent types added in NDB 7.4.3 (Bug #20646496); in NDB 7.4.7 and later, pollEvents() is compatible with these event types, as described later in this section.

Signature. 

int pollEvents
    (
      int     maxTimeToWait,
      Uint64* latestGCI = 0
    )

Parameters.  This method takes the two parameters listed here:

  • The maximum time to wait, in milliseconds, before giving up and reporting that no events were available (that is, before the method automatically returns 0).

    A negative value causes the wait to be indefinite and never time out. This is not recommended (and is not supported by the successor method pollEvents2()).

  • The index of the most recent global checkpoint. Normally, this may safely be permitted to assume its default value, which is 0.

Return value.  pollEvents() returns a value of type int, which may be interpreted as follows:

  • > 0: There are events available in the queue.

  • 0: There are no events available.

  • In NDB 7.4.7 and later, a negative value indicates failure and NDB_FAILURE_GCI (~(Uint64)0) indicates cluster failure (Bug #18753887); 1 is returned when encountering an exceptional event, except when only TE_EMPTY events are found, as described later in this section.

In NDB 7.4.7 and later, when pollEvents() finds an exceptional event at the head of the event queue, the method returns 1 and otherwise behaves as follows:

  • Empty events (TE_EMPTY) are removed from the event queue head until an event containing data is found. When this results in the entire queue being processed without encountering any data, the method returns 0 (no events available) rather than 1. This behavior makes this event type transparent to an application using pollEvents().

  • After encountering an event containing inconsistent data (TE_INCONSISTENT) due to data node buffer overflow, the next call to nextEvent() call removes the inconsistent data event data from the event queue, and returns NULL. You should check the inconsistency by calling isConsistent() immediately thereafter.

    Important: Although the inconsistent event data is removed from the event queue by calling nextEvent(), information about the inconsistency is removed only by another nextEvent() call following this, that actually finds an event containing data.

  • When pollEvents() finds a data buffer overflow event (TE_OUT_OF_MEMORY), the event data is added to the event queue whenever event buffer usage exceeds ndb_eventbuffer_max_alloc. In this case, the next call to nextEvent() exits the process.


User Comments
Sign Up Login You must be logged in to post a comment.