Producer shouldn't require a fixed partition number

[StarLightPL]

By forcing a partition number, you move the responsibility of balancing partitions to the user. This might lead to imbalanced partitions and workers having problems processing message from these partitions. Usually Kafka clients partition messages using some kind of random algorithm, or partition messages using keys. You should avoid forcing the user to explicitly assign partition unless it's really necessary and mention the pitfalls of doing so.

Ideally you should provide a partitioner which is not exposed to the user unless requested. Librdkafka provides one and it's fast. If that's impossible, I propose a simple fix to the documentation which will include a random partition assignment for the producer:

my $topic = 'mytopic';
my $metadata = $connection->get_metadata($topic);                              
my $partitions_count =  scalar keys %{$metadata->{$topic}};

# Sending a single message
my $response = $producer->send(
    $topic,          # topic
    int(rand($partitions_count),                  # partition
    'Single message'    # message
);

This doesn't solve sending a list of messages to the same partition which is far from ideal. That's why it should be provided internally.

[asolovey]

This library is considered rather low-level, and so original intent was to provide building blocks for advanced uses, instead of trying to implement all of them in the library itself.

I like your idea to update documentation with an example of simple partitioner - it will provide a good starting point and at the same time, won't limit library users to a specific partition selection strategy - they are free to plug in any partitioner.