producer.rb in ruby-kafka-0.1.2

- old
+ new

@@ -5,10 +5,24 @@
 
 module Kafka
 
   # Allows sending messages to a Kafka cluster.
   #
+  # Typically you won't instantiate this class yourself, but rather have {Kafka::Client}
+  # do it for you, e.g.
+  #
+  #     # Will instantiate Kafka::Client
+  #     kafka = Kafka.new(...)
+  #
+  #     # Will instantiate Kafka::Producer
+  #     producer = kafka.get_producer
+  #
+  # This is done in order to share a logger as well as a pool of broker connections across
+  # different producers. This also means that you don't need to pass the `broker_pool` and
+  # `logger` options to `#get_producer`. See {#initialize} for the list of other options
+  # you can pass in.
+  #
   # ## Buffering
   #
   # The producer buffers pending messages until {#send_messages} is called. Note that there is
   # a maximum buffer size (default is 1,000 messages) and writing messages after the
   # buffer has reached this size will result in a BufferOverflow exception. Make sure
@@ -71,12 +85,14 @@
   class Producer
 
     # Initializes a new Producer.
     #
     # @param broker_pool [BrokerPool] the broker pool representing the cluster.
+    #   Typically passed in for you.
     #
-    # @param logger [Logger]
+    # @param logger [Logger] the logger that should be used. Typically passed
+    #   in for you.
     #
     # @param ack_timeout [Integer] The number of seconds a broker can wait for
     #   replicas to acknowledge a write before responding with a timeout.
     #
     # @param required_acks [Integer] The number of replicas that must acknowledge
@@ -89,10 +105,10 @@
     # @param retry_backoff [Integer] the number of seconds to wait between retries.
     #
     # @param max_buffer_size [Integer] the number of messages allowed in the buffer
     #   before new writes will raise BufferOverflow exceptions.
     #
-    def initialize(broker_pool:, logger:, ack_timeout: 10, required_acks: 1, max_retries: 2, retry_backoff: 1, max_buffer_size: 1000)
+    def initialize(broker_pool:, logger:, ack_timeout: 5, required_acks: 1, max_retries: 2, retry_backoff: 1, max_buffer_size: 1000)
       @broker_pool = broker_pool
       @logger = logger
       @required_acks = required_acks
       @ack_timeout = ack_timeout
       @max_retries = max_retries