merlimat commented on a change in pull request #574: Documentation changes
URL: https://github.com/apache/incubator-pulsar/pull/574#discussion_r129221412
##########
File path: site/_includes/explanations/partitioned-topics.md
##########
@@ -1,19 +1,31 @@
-Normal topics can be served only by a single {% popover broker %}, which
limits the topic's maximum throughput. *Partitioned topics* are a special type
of topic that can span multiple brokers and thus allow for much higher
throughput.
+Normal topics can be served only by a single {% popover broker %}, which
limits the topic's maximum throughput. *Partitioned topics* are a special type
of topic that be handled by multiple brokers, which allows for much higher
throughput.
-Behind the scenes, a partitioned topic is actually implemented as N internal
topics, where N is the number of partitions. There is no difference between
partitioned topics and other normal topics in terms of how subscription modes
work.
+Behind the scenes, a partitioned topic is actually 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:
+
+
+
+Here, the topic **T1** has five partitions (**P0** through **P4**) split
across three brokers. Because there are more partitions than brokers, two
brokers handle two partitions a piece, while the third handles only one (again,
Pulsar handles this distribution of partitions automatically).
+
+Messages for this topic are broadcast to two {% popover consumers %}. The
[routing mode](#routing-modes) determines both which broker handles each
partition, while the [subscription
mode](../../getting-started/ConceptsAndArchitecture#subscription-modes)
determines which messages go to which consumers.
+
+Decisions about routing and subscription modes can be made separately in most
cases. Throughput concerns should guide partitioning/routing decisions while
subscription decisions should be guided by application semantics.
+
+There is no difference between partitioned topics and normal topics in terms
of how subscription modes work, as partitioning only determines what happens
between when a message is published by a {% popover producer %} and processed
and {% popover acknowledged %} by a {% popover consumer %}.
Partitioned topics need to be explicitly created via the [admin
API](../../admin/AdminInterface). The number of partitions can be specified
when creating the topic.
-The diagram below illustrates this:
+#### Routing modes
-
+When publishing to partitioned topics, you must specify a *routing mode*. The
routing mode determines which partition---that is, which internal topic---each
message should be published to.
Review comment:
> ... you must specify...
Actually, you don't have to explicitly chose one, because the default would
be to use the "Single default partition"
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
With regards,
Apache Git Services
