Anonymitaet commented on code in PR #671: URL: https://github.com/apache/pulsar-site/pull/671#discussion_r1287851146
########## docs/concepts-messaging.md: ########## @@ -486,13 +492,20 @@ If no tenant or namespace is specified when a client creates a topic, the topic ## Namespaces -A namespace is a logical nomenclature within a tenant. A tenant creates namespaces via the [admin API](admin-api-namespaces.md#create-namespaces). For instance, a tenant with different applications can create a separate namespace for each application. A namespace allows the application to create and manage a hierarchy of topics. The topic `my-tenant/app1` is a namespace for the application `app1` for `my-tenant`. You can create any number of [topics](#topics) under the namespace. +Pulsar namespaces are logical groupings of topics. A namespace is a logical nomenclature within a tenant. A tenant creates namespaces via the [admin API](admin-api-namespaces.md#create-namespaces). For instance, a tenant with different applications can create a separate namespace for each application. A namespace allows the application to create and manage a hierarchy of topics. The topic `my-tenant/app1` is a namespace for the application `app1` for `my-tenant`. You can create any number of [topics](#topics) under the namespace. ## Subscriptions -A subscription is a named configuration rule that determines how messages are delivered to consumers. Four subscription types are available in Pulsar: [exclusive](#exclusive), [shared](#shared), [failover](#failover), and [key_shared](#key_shared). These types are illustrated in the figure below. +A Pulsar subscription is a lease on a topic established by a group of consumers, it is a named configuration rule that determines how messages are delivered to consumers. There are four available subscription types in Pulsar: Review Comment: same as https://github.com/apache/pulsar-site/pull/671#discussion_r1287836845 ########## docs/concepts-messaging.md: ########## @@ -520,11 +533,11 @@ Exclusive is the default subscription type. ::: - + Review Comment: ```suggestion  ``` ########## docs/concepts-messaging.md: ########## @@ -560,7 +573,7 @@ A consumer is selected by running a module operation `mod (partition index, cons - for P1: Consumer D is the active consumer and Consumer C is the stand-by consumer. -  +  Review Comment: ```suggestion  ``` ########## docs/concepts-messaging.md: ########## @@ -594,11 +607,11 @@ A consumer is selected by running a module operation `mod (partition index, cons - The non-partitioned topic 2 and non-partitioned topic 3 are assigned to consumer A. Consumer B is their stand-by consumer. -  +  #### Shared -In *shared* or *round robin* type, multiple consumers can attach to the same subscription. Messages are delivered in a round-robin distribution across consumers, and any given message is delivered to only one consumer. When a consumer disconnects, all the messages that were sent to it and not acknowledged will be rescheduled for sending to the remaining consumers. +The Pulsar Shared subscriptions allow multiple consumers attach to the same subscription. Messages are delivered in a round-robin distribution across consumers, and any given message is delivered to only one consumer. When a consumer disconnects, all the messages that were sent to it and not acknowledged will be rescheduled for sending to the remaining consumers. Review Comment: ```suggestion The shared subscription type in Pulsar allows multiple consumers to attach to the same subscription. Messages are delivered in a round-robin distribution across consumers, and any given message is delivered to only one consumer. When a consumer disconnects, all the messages that were sent to it and not acknowledged will be rescheduled for sending to the remaining consumers. ``` ########## docs/concepts-messaging.md: ########## @@ -608,13 +621,13 @@ Shared subscriptions do not guarantee message ordering or support cumulative ack ::: - + #### Key_Shared -In the *Key_Shared* type, multiple consumers can attach to the same subscription. Messages are delivered in distribution across consumers and messages with the same key or same ordering key are delivered to only one consumer. No matter how many times the message is re-delivered, it is delivered to the same consumer. +The Pulsar Key_Shared subscriptions allow multiple consumers attach to the same subscription. But different with the Shared type, messages in Key_Shared type are delivered in distribution across consumers and messages with the same key or same ordering key are delivered to only one consumer. No matter how many times the message is re-delivered, it is delivered to the same consumer. Review Comment: ```suggestion The Key_Shared subscription type in Pulsar allows multiple consumers to attach to the same subscription. But different with the Shared type, messages in the Key_Shared type are delivered in distribution across consumers and messages with the same key or same ordering key are delivered to only one consumer. No matter how many times the message is re-delivered, it is delivered to the same consumer. ``` ########## docs/concepts-messaging.md: ########## @@ -941,13 +961,13 @@ For code examples, see [Java](client-libraries-java.md#multi-topic-subscriptions ## Partitioned topics -Normal topics are served only by a single broker, which limits the maximum throughput of the topic. *Partitioned topics* are a special type of topic handled by multiple brokers, thus allowing for higher throughput. +Normal topics are served only by a single broker, which limits the maximum throughput of the topic. Partitioned topic is a special type of topic handled by multiple brokers, thus allowing for higher throughput. A partitioned topic is implemented as N internal topics, where N is the number of partitions. When publishing messages to a partitioned topic, each message is routed to one of several brokers. The distribution of partitions across brokers is handled automatically by Pulsar. The diagram below illustrates this: - + Review Comment: ```suggestion  ``` ########## docs/concepts-messaging.md: ########## @@ -1084,7 +1108,7 @@ Apache Pulsar supports graceful failure handling and ensures critical data is no - Consumers get disconnected from the database or the HTTP server. When this happens, the database is temporarily offline while the consumer is writing the data to it and the external HTTP server that the consumer calls are momentarily unavailable. - Consumers get disconnected from a broker due to consumer crashes, broken connections, etc. As a consequence, unacknowledged messages are delivered to other available consumers. -Apache Pulsar avoids these and other message delivery failures using at-least-once delivery semantics that ensure Pulsar processes a message more than once. +Message redelivery in Apache Pulsar avoids these and other message delivery failures using at-least-once delivery semantics that ensure Pulsar processes a message more than once. Review Comment: What does "these" refer to? Please specify them explicitly ########## docs/concepts-messaging.md: ########## @@ -486,13 +492,20 @@ If no tenant or namespace is specified when a client creates a topic, the topic ## Namespaces -A namespace is a logical nomenclature within a tenant. A tenant creates namespaces via the [admin API](admin-api-namespaces.md#create-namespaces). For instance, a tenant with different applications can create a separate namespace for each application. A namespace allows the application to create and manage a hierarchy of topics. The topic `my-tenant/app1` is a namespace for the application `app1` for `my-tenant`. You can create any number of [topics](#topics) under the namespace. +Pulsar namespaces are logical groupings of topics. A namespace is a logical nomenclature within a tenant. A tenant creates namespaces via the [admin API](admin-api-namespaces.md#create-namespaces). For instance, a tenant with different applications can create a separate namespace for each application. A namespace allows the application to create and manage a hierarchy of topics. The topic `my-tenant/app1` is a namespace for the application `app1` for `my-tenant`. You can create any number of [topics](#topics) under the namespace. ## Subscriptions -A subscription is a named configuration rule that determines how messages are delivered to consumers. Four subscription types are available in Pulsar: [exclusive](#exclusive), [shared](#shared), [failover](#failover), and [key_shared](#key_shared). These types are illustrated in the figure below. +A Pulsar subscription is a lease on a topic established by a group of consumers, it is a named configuration rule that determines how messages are delivered to consumers. There are four available subscription types in Pulsar: + +- [exclusive](#exclusive) +- [shared](#shared) +- [failover](#failover) +- [key_shared](#key_shared) + +These types are illustrated in the figure below. - + Review Comment: ```suggestion  ``` ########## docs/concepts-messaging.md: ########## @@ -486,13 +492,20 @@ If no tenant or namespace is specified when a client creates a topic, the topic ## Namespaces -A namespace is a logical nomenclature within a tenant. A tenant creates namespaces via the [admin API](admin-api-namespaces.md#create-namespaces). For instance, a tenant with different applications can create a separate namespace for each application. A namespace allows the application to create and manage a hierarchy of topics. The topic `my-tenant/app1` is a namespace for the application `app1` for `my-tenant`. You can create any number of [topics](#topics) under the namespace. +Pulsar namespaces are logical groupings of topics. A namespace is a logical nomenclature within a tenant. A tenant creates namespaces via the [admin API](admin-api-namespaces.md#create-namespaces). For instance, a tenant with different applications can create a separate namespace for each application. A namespace allows the application to create and manage a hierarchy of topics. The topic `my-tenant/app1` is a namespace for the application `app1` for `my-tenant`. You can create any number of [topics](#topics) under the namespace. Review Comment: same as https://github.com/apache/pulsar-site/pull/671#discussion_r1287836845 ########## docs/concepts-messaging.md: ########## @@ -510,7 +523,7 @@ When a subscription has no consumers, its subscription type is undefined. The ty #### Exclusive -In the *Exclusive* type, only a single consumer is allowed to attach to the subscription. If multiple consumers subscribe to a topic using the same subscription, an error occurs. Note that if the topic is partitioned, all partitions will be consumed by the single consumer allowed to be connected to the subscription. +The Exclusive type is a subscription mode that only allows a single consumer to attach to the subscription. If multiple consumers subscribe to a topic using the same subscription, an error occurs. Note that if the topic is partitioned, all partitions will be consumed by the single consumer allowed to be connected to the subscription. Review Comment: ```suggestion The exclusive type is a subscription type that only allows a single consumer to attach to the subscription. If multiple consumers subscribe to a topic using the same subscription, an error occurs. Note that if the topic is partitioned, all partitions will be consumed by the single consumer allowed to be connected to the subscription. ``` ########## docs/concepts-messaging.md: ########## @@ -572,7 +585,7 @@ A consumer is selected by running a module operation `mod (partition index, cons - P2, P5, and P8 are assigned to Consumer C. Consumer C is their active consumer. Consumer A and Consumer B are their stand-by consumers. -  +  Review Comment: ```suggestion  ``` Keep it as concise as possible ########## docs/concepts-messaging.md: ########## @@ -584,7 +597,7 @@ A consumer is selected by running a module operation `mod (partition index, cons Consumer A is the master consumer, while consumer B would be the next consumer in line to receive messages if consumer A is disconnected. -  +  Review Comment: ```suggestion  ``` ########## docs/concepts-messaging.md: ########## @@ -608,13 +621,13 @@ Shared subscriptions do not guarantee message ordering or support cumulative ack ::: - + #### Key_Shared -In the *Key_Shared* type, multiple consumers can attach to the same subscription. Messages are delivered in distribution across consumers and messages with the same key or same ordering key are delivered to only one consumer. No matter how many times the message is re-delivered, it is delivered to the same consumer. +The Pulsar Key_Shared subscriptions allow multiple consumers attach to the same subscription. But different with the Shared type, messages in Key_Shared type are delivered in distribution across consumers and messages with the same key or same ordering key are delivered to only one consumer. No matter how many times the message is re-delivered, it is delivered to the same consumer. - + Review Comment: ```suggestion  ``` ########## docs/concepts-messaging.md: ########## @@ -594,11 +607,11 @@ A consumer is selected by running a module operation `mod (partition index, cons - The non-partitioned topic 2 and non-partitioned topic 3 are assigned to consumer A. Consumer B is their stand-by consumer. -  +  Review Comment: ```suggestion  ``` ########## docs/concepts-messaging.md: ########## @@ -520,11 +533,11 @@ Exclusive is the default subscription type. ::: - + #### Failover -In the *Failover* type, multiple consumers can attach to the same subscription. +The Failover type is a subscription mode that multiple consumers can attach to the same subscription. Review Comment: ```suggestion The failover type is a subscription type that multiple consumers can attach to the same subscription. ``` ########## docs/concepts-overview.md: ########## @@ -2,6 +2,7 @@ id: concepts-overview title: Pulsar Overview sidebar_label: "Overview" +description: Apache Pulsar is a multi-tenant, high-performance solution for server-to-server messaging. Review Comment: ```suggestion description: Key features of Pulsar ``` ########## docs/concepts-messaging.md: ########## @@ -608,13 +621,13 @@ Shared subscriptions do not guarantee message ordering or support cumulative ack ::: - + Review Comment: ```suggestion  ``` ########## docs/concepts-messaging.md: ########## @@ -486,13 +492,20 @@ If no tenant or namespace is specified when a client creates a topic, the topic ## Namespaces -A namespace is a logical nomenclature within a tenant. A tenant creates namespaces via the [admin API](admin-api-namespaces.md#create-namespaces). For instance, a tenant with different applications can create a separate namespace for each application. A namespace allows the application to create and manage a hierarchy of topics. The topic `my-tenant/app1` is a namespace for the application `app1` for `my-tenant`. You can create any number of [topics](#topics) under the namespace. +Pulsar namespaces are logical groupings of topics. A namespace is a logical nomenclature within a tenant. A tenant creates namespaces via the [admin API](admin-api-namespaces.md#create-namespaces). For instance, a tenant with different applications can create a separate namespace for each application. A namespace allows the application to create and manage a hierarchy of topics. The topic `my-tenant/app1` is a namespace for the application `app1` for `my-tenant`. You can create any number of [topics](#topics) under the namespace. ## Subscriptions -A subscription is a named configuration rule that determines how messages are delivered to consumers. Four subscription types are available in Pulsar: [exclusive](#exclusive), [shared](#shared), [failover](#failover), and [key_shared](#key_shared). These types are illustrated in the figure below. +A Pulsar subscription is a lease on a topic established by a group of consumers, it is a named configuration rule that determines how messages are delivered to consumers. There are four available subscription types in Pulsar: Review Comment: ```suggestion A Pulsar subscription is a named configuration rule that determines how messages are delivered to consumers. It is a lease on a topic established by a group of consumers. There are four subscription types in Pulsar: ``` ########## docs/concepts-messaging.md: ########## @@ -1016,7 +1040,7 @@ Currently, non-persistent topics which are not partitioned are not persisted to ### Performance -Non-persistent messaging is usually faster than persistent messaging because brokers don't persist messages and immediately send acks back to the producer as soon as that message is delivered to connected brokers. Producers thus see comparatively low publish latency with non-persistent topic. +With persistent topics, all messages are durably persisted on disks, whereas with non-persistent topics, brokers don't persist messages and immediately send acks back to the producer as soon as that message is delivered to connected brokers, so Non-persistent messaging is usually faster than persistent messaging. Producers thus see comparatively low publish latency with non-persistent topic. Review Comment: ```suggestion With persistent topics, all messages are durably persisted on disks, whereas with non-persistent topics, brokers don't persist messages and immediately send acks back to the producer as soon as that message is delivered to connected brokers, so non-persistent messaging is usually faster than persistent messaging. Producers thus see comparatively low publish latency with non-persistent topics. ``` ########## docs/concepts-messaging.md: ########## @@ -1138,7 +1162,7 @@ In the second scenario at the bottom, the producer publishes message 1, which is ### Producer idempotency -The other available approach to message deduplication is to ensure that each message is *only produced once*. This approach is typically called **producer idempotency**. The drawback of this approach is that it defers the work of message deduplication to the application. In Pulsar, this is handled at the [broker](reference-terminology.md#broker) level, so you do not need to modify your Pulsar client code. Instead, you only need to make administrative changes. For details, see [Managing message deduplication](cookbooks-deduplication.md). +The other available approach is typically called **producer idempotency**, that is, each message is *only produced once* without data loss and duplicatuion. The drawback of this approach is that it defers the work of message deduplication to the application. In Pulsar, this is handled at the [broker](reference-terminology.md#broker) level, so you do not need to modify your Pulsar client code. Instead, you only need to make administrative changes. For details, see [Managing message deduplication](cookbooks-deduplication.md). Review Comment: ```suggestion The other available approach to message deduplication is **producer idempotency**, which means each message is *only produced once* without data loss and duplication. The drawback of this approach is that it defers the work of message deduplication to the application. In Pulsar, this is handled at the [broker](reference-terminology.md#broker) level, so you do not need to modify your Pulsar client code. Instead, you only need to make administrative changes. For details, see [Managing message deduplication](cookbooks-deduplication.md). ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
