kafka-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j...@apache.org
Subject [kafka] branch 1.1 updated: MINOR: Make it explicit in consumer docs that poll() is needed for callback to run (#4480)
Date Fri, 16 Feb 2018 16:28:05 GMT
This is an automated email from the ASF dual-hosted git repository.

jgus pushed a commit to branch 1.1
in repository https://gitbox.apache.org/repos/asf/kafka.git


The following commit(s) were added to refs/heads/1.1 by this push:
     new 9a18a04  MINOR: Make it explicit in consumer docs that poll() is needed for callback
to run (#4480)
9a18a04 is described below

commit 9a18a048d7aa2107073da0d15d780dd8e729eac9
Author: dan norwood <dan.norwood@gmail.com>
AuthorDate: Fri Feb 16 08:24:04 2018 -0800

    MINOR: Make it explicit in consumer docs that poll() is needed for callback to run (#4480)
    
    Make it clear in the docs that the rebalance listener is only invoked during an active
call to `poll()`. Plus a few additional doc cleanups.
    
    Reviewers: Ismael Juma <ismael@juma.me.uk>, Jason Gustafson <jason@confluent.io>
---
 .../consumer/ConsumerRebalanceListener.java        |  4 +--
 .../kafka/clients/consumer/KafkaConsumer.java      | 36 +++++++++++-----------
 2 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerRebalanceListener.java
b/clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerRebalanceListener.java
index 845bff3..a37e166 100644
--- a/clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerRebalanceListener.java
+++ b/clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerRebalanceListener.java
@@ -44,7 +44,7 @@ import org.apache.kafka.common.TopicPartition;
  * partition is reassigned it may want to automatically trigger a flush of this cache, before
the new owner takes over
  * consumption.
  * <p>
- * This callback will execute in the user thread as part of the {@link Consumer#poll(long)
poll(long)} call whenever partition assignment changes.
+ * This callback will only execute in the user thread as part of the {@link Consumer#poll(long)
poll(long)} call whenever partition assignment changes.
  * <p>
  * It is guaranteed that all consumer processes will invoke {@link #onPartitionsRevoked(Collection)
onPartitionsRevoked} prior to
  * any process invoking {@link #onPartitionsAssigned(Collection) onPartitionsAssigned}. So
if offsets or other state is saved in the
@@ -103,7 +103,7 @@ public interface ConsumerRebalanceListener {
     /**
      * A callback method the user can implement to provide handling of customized offsets
on completion of a successful
      * partition re-assignment. This method will be called after an offset re-assignment
completes and before the
-     * consumer starts fetching data.
+     * consumer starts fetching data, and only as the result of a {@link Consumer#poll(long)
poll(long)} call.
      * <p>
      * It is guaranteed that all the processes in a consumer group will execute their
      * {@link #onPartitionsRevoked(Collection)} callback before any instance executes its
diff --git a/clients/src/main/java/org/apache/kafka/clients/consumer/KafkaConsumer.java b/clients/src/main/java/org/apache/kafka/clients/consumer/KafkaConsumer.java
index cbe54c7..ad96ecf 100644
--- a/clients/src/main/java/org/apache/kafka/clients/consumer/KafkaConsumer.java
+++ b/clients/src/main/java/org/apache/kafka/clients/consumer/KafkaConsumer.java
@@ -868,17 +868,20 @@ public class KafkaConsumer<K, V> implements Consumer<K, V>
{
      *
      * <p>
      * As part of group management, the consumer will keep track of the list of consumers
that belong to a particular
-     * group and will trigger a rebalance operation if one of the following events trigger
-
+     * group and will trigger a rebalance operation if any one of the following events are
triggered:
      * <ul>
-     * <li>Number of partitions change for any of the subscribed list of topics
-     * <li>Topic is created or deleted
-     * <li>An existing member of the consumer group dies
-     * <li>A new member is added to an existing consumer group via the join API
+     * <li>Number of partitions change for any of the subscribed topics
+     * <li>A subscribed topic is created or deleted
+     * <li>An existing member of the consumer group is shutdown or fails
+     * <li>A new member is added to the consumer group
      * </ul>
      * <p>
      * When any of these events are triggered, the provided listener will be invoked first
to indicate that
      * the consumer's assignment has been revoked, and then again when the new assignment
has been received.
-     * Note that this listener will immediately override any listener set in a previous call
to subscribe.
+     * Note that rebalances will only occur during an active call to {@link #poll(long)},
so callbacks will
+     * also only be invoked during that time.
+     *
+     * The provided listener will immediately override any listener set in a previous call
to subscribe.
      * It is guaranteed, however, that the partitions revoked/assigned through this interface
are from topics
      * subscribed in this call. See {@link ConsumerRebalanceListener} for more details.
      *
@@ -926,7 +929,7 @@ public class KafkaConsumer<K, V> implements Consumer<K, V>
{
      *
      * <p>
      * This is a short-hand for {@link #subscribe(Collection, ConsumerRebalanceListener)},
which
-     * uses a noop listener. If you need the ability to seek to particular offsets, you should
prefer
+     * uses a no-op listener. If you need the ability to seek to particular offsets, you
should prefer
      * {@link #subscribe(Collection, ConsumerRebalanceListener)}, since group rebalances
will cause partition offsets
      * to be reset. You should also provide your own listener if you are doing your own offset
      * management since the listener gives you an opportunity to commit offsets before a
rebalance finishes.
@@ -944,17 +947,14 @@ public class KafkaConsumer<K, V> implements Consumer<K, V>
{
 
     /**
      * Subscribe to all topics matching specified pattern to get dynamically assigned partitions.
-     * The pattern matching will be done periodically against topic existing at the time
of check.
+     * The pattern matching will be done periodically against all topics existing at the
time of check.
+     * This can be controlled through the {@code metadata.max.age.ms} configuration: by lowering
+     * the max metadata age, the consumer will refresh metadata more often and check for
matching topics.
      * <p>
-     * As part of group management, the consumer will keep track of the list of consumers
that
-     * belong to a particular group and will trigger a rebalance operation if one of the
-     * following events trigger -
-     * <ul>
-     * <li>Number of partitions change for any of the subscribed list of topics
-     * <li>Topic is created or deleted
-     * <li>An existing member of the consumer group dies
-     * <li>A new member is added to an existing consumer group via the join API
-     * </ul>
+     * See {@link #subscribe(Collection, ConsumerRebalanceListener)} for details on the
+     * use of the {@link ConsumerRebalanceListener}. Generally rebalances are triggered when
there
+     * is a change to the topics matching the provided pattern and when consumer group membership
changes.
+     * Group rebalances only take place during an active call to {@link #poll(long)}.
      *
      * @param pattern Pattern to subscribe to
      * @param listener Non-null listener instance to get notifications on partition assignment/revocation
for the
@@ -988,7 +988,7 @@ public class KafkaConsumer<K, V> implements Consumer<K, V>
{
      * The pattern matching will be done periodically against topics existing at the time
of check.
      * <p>
      * This is a short-hand for {@link #subscribe(Pattern, ConsumerRebalanceListener)}, which
-     * uses a noop listener. If you need the ability to seek to particular offsets, you should
prefer
+     * uses a no-op listener. If you need the ability to seek to particular offsets, you
should prefer
      * {@link #subscribe(Pattern, ConsumerRebalanceListener)}, since group rebalances will
cause partition offsets
      * to be reset. You should also provide your own listener if you are doing your own offset
      * management since the listener gives you an opportunity to commit offsets before a
rebalance finishes.

-- 
To stop receiving notification emails like this one, please contact
jgus@apache.org.

Mime
View raw message