rdkafka 0.24.2 → 0.25.0

data/lib/rdkafka/consumer.rb

@@ -16,6 +16,7 @@ module Rdkafka
     include Helpers::OAuth
 
     # @private
+    # @param native_kafka [NativeKafka] wrapper around the native Kafka consumer handle
     def initialize(native_kafka)
       @native_kafka = native_kafka
     end
@@ -33,6 +34,8 @@ module Rdkafka
       end
     end
 
+    # @return [Proc] finalizer proc for closing the consumer
+    # @private
     def finalizer
       ->(_) { close }
     end
@@ -67,14 +70,14 @@ module Rdkafka
       tpl = Rdkafka::Bindings.rd_kafka_topic_partition_list_new(topics.length)
 
       topics.each do |topic|
-        Rdkafka::Bindings.rd_kafka_topic_partition_list_add(tpl, topic, -1)
+        Rdkafka::Bindings.rd_kafka_topic_partition_list_add(tpl, topic, Rdkafka::Bindings::RD_KAFKA_PARTITION_UA)
       end
 
       # Subscribe to topic partition list and check this was successful
       response = @native_kafka.with_inner do |inner|
         Rdkafka::Bindings.rd_kafka_subscribe(inner, tpl)
       end
-      if response != 0
+      if response != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
         raise Rdkafka::RdkafkaError.new(response, "Error subscribing to '#{topics.join(', ')}'")
       end
     ensure
@@ -91,7 +94,7 @@ module Rdkafka
       response = @native_kafka.with_inner do |inner|
         Rdkafka::Bindings.rd_kafka_unsubscribe(inner)
       end
-      if response != 0
+      if response != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
         raise Rdkafka::RdkafkaError.new(response)
       end
     end
@@ -115,7 +118,7 @@ module Rdkafka
           Rdkafka::Bindings.rd_kafka_pause_partitions(inner, tpl)
         end
 
-        if response != 0
+        if response != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
           list = TopicPartitionList.from_native_tpl(tpl)
           raise Rdkafka::RdkafkaTopicPartitionListError.new(response, list, "Error pausing '#{list.to_h}'")
         end
@@ -142,7 +145,7 @@ module Rdkafka
         response = @native_kafka.with_inner do |inner|
           Rdkafka::Bindings.rd_kafka_resume_partitions(inner, tpl)
         end
-        if response != 0
+        if response != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
           raise Rdkafka::RdkafkaError.new(response, "Error resume '#{list.to_h}'")
         end
       ensure
@@ -162,7 +165,7 @@ module Rdkafka
         Rdkafka::Bindings.rd_kafka_subscription(inner, ptr)
       end
 
-      if response != 0
+      if response != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
         raise Rdkafka::RdkafkaError.new(response)
       end
 
@@ -192,7 +195,7 @@ module Rdkafka
         response = @native_kafka.with_inner do |inner|
           Rdkafka::Bindings.rd_kafka_assign(inner, tpl)
         end
-        if response != 0
+        if response != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
           raise Rdkafka::RdkafkaError.new(response, "Error assigning '#{list.to_h}'")
         end
       ensure
@@ -211,7 +214,7 @@ module Rdkafka
       response = @native_kafka.with_inner do |inner|
         Rdkafka::Bindings.rd_kafka_assignment(inner, ptr)
       end
-      if response != 0
+      if response != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
         raise Rdkafka::RdkafkaError.new(response)
       end
 
@@ -246,7 +249,7 @@ module Rdkafka
     # @param timeout_ms [Integer] The timeout for fetching this information.
     # @return [TopicPartitionList]
     # @raise [RdkafkaError] When getting the committed positions fails.
-    def committed(list=nil, timeout_ms=2_000)
+    def committed(list = nil, timeout_ms = Defaults::CONSUMER_COMMITTED_TIMEOUT_MS)
       closed_consumer_check(__method__)
 
       if list.nil?
@@ -261,7 +264,7 @@ module Rdkafka
         response = @native_kafka.with_inner do |inner|
           Rdkafka::Bindings.rd_kafka_committed(inner, tpl, timeout_ms)
         end
-        if response != 0
+        if response != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
           raise Rdkafka::RdkafkaError.new(response)
         end
         TopicPartitionList.from_native_tpl(tpl)
@@ -291,7 +294,7 @@ module Rdkafka
         Rdkafka::Bindings.rd_kafka_position(inner, tpl)
       end
 
-      if response != 0
+      if response != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
         raise Rdkafka::RdkafkaError.new(response)
       end
 
@@ -305,7 +308,7 @@ module Rdkafka
     # @param timeout_ms [Integer] The timeout for querying the broker
     # @return [Integer] The low and high watermark
     # @raise [RdkafkaError] When querying the broker fails.
-    def query_watermark_offsets(topic, partition, timeout_ms=1000)
+    def query_watermark_offsets(topic, partition, timeout_ms = Defaults::CONSUMER_QUERY_WATERMARK_TIMEOUT_MS)
       closed_consumer_check(__method__)
 
       low = FFI::MemoryPointer.new(:int64, 1)
@@ -321,7 +324,7 @@ module Rdkafka
           timeout_ms,
         )
       end
-      if response != 0
+      if response != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
         raise Rdkafka::RdkafkaError.new(response, "Error querying watermark offsets for partition #{partition} of #{topic}")
       end
 
@@ -338,10 +341,10 @@ module Rdkafka
     #
     # @param topic_partition_list [TopicPartitionList] The list to calculate lag for.
     # @param watermark_timeout_ms [Integer] The timeout for each query watermark call.
-    # @return [Hash<String, Hash<Integer, Integer>>] A hash containing all topics with the lag
+    # @return [Hash{String => Hash{Integer => Integer}}] A hash containing all topics with the lag
     #   per partition
     # @raise [RdkafkaError] When querying the broker fails.
-    def lag(topic_partition_list, watermark_timeout_ms=1000)
+    def lag(topic_partition_list, watermark_timeout_ms = Defaults::CONSUMER_LAG_TIMEOUT_MS)
       out = {}
 
       topic_partition_list.to_h.each do |topic, partitions|
@@ -409,7 +412,7 @@ module Rdkafka
         )
       end
 
-      if response != 0
+      if response != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
         raise Rdkafka::RdkafkaError.new(response)
       end
     ensure
@@ -451,9 +454,9 @@ module Rdkafka
         native_topic,
         partition,
         offset,
-        0 # timeout
+        Defaults::CONSUMER_SEEK_TIMEOUT_MS
       )
-      if response != 0
+      if response != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
         raise Rdkafka::RdkafkaError.new(response)
       end
     ensure
@@ -465,11 +468,10 @@ module Rdkafka
     # Lookup offset for the given partitions by timestamp.
     #
     # @param list [TopicPartitionList] The TopicPartitionList with timestamps instead of offsets
-    #
+    # @param timeout_ms [Integer] timeout in milliseconds for the operation
     # @return [TopicPartitionList]
-    #
     # @raise [RdKafkaError] When the OffsetForTimes lookup fails
-    def offsets_for_times(list, timeout_ms = 1000)
+    def offsets_for_times(list, timeout_ms = Defaults::CONSUMER_OFFSETS_FOR_TIMES_TIMEOUT_MS)
       closed_consumer_check(__method__)
 
       if !list.is_a?(TopicPartitionList)
@@ -486,7 +488,7 @@ module Rdkafka
         )
       end
 
-      if response != 0
+      if response != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
         raise Rdkafka::RdkafkaError.new(response)
       end
 
@@ -521,7 +523,7 @@ module Rdkafka
         response = @native_kafka.with_inner do |inner|
           Rdkafka::Bindings.rd_kafka_commit(inner, tpl, async)
         end
-        if response != 0
+        if response != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
           raise Rdkafka::RdkafkaError.new(response)
         end
       ensure
@@ -546,7 +548,7 @@ module Rdkafka
         # Create struct wrapper
         native_message = Rdkafka::Bindings::Message.new(message_ptr)
         # Raise error if needed
-        if native_message[:err] != 0
+        if native_message[:err] != Rdkafka::Bindings::RD_KAFKA_RESP_ERR_NO_ERROR
           raise Rdkafka::RdkafkaError.new(native_message[:err])
         end
         # Create a message to pass out
@@ -579,7 +581,7 @@ module Rdkafka
     # @note This method technically should be called `#poll` and the current `#poll` should be
     #   called `#consumer_poll` though we keep the current naming convention to make it backward
     #   compatible.
-    def events_poll(timeout_ms = 0)
+    def events_poll(timeout_ms = Defaults::CONSUMER_EVENTS_POLL_TIMEOUT_MS)
       @native_kafka.with_inner do |inner|
         Rdkafka::Bindings.rd_kafka_poll(inner, timeout_ms)
       end
@@ -591,12 +593,13 @@ module Rdkafka
     # If `enable.partition.eof` is turned on in the config this will raise an error when an eof is
     # reached, so you probably want to disable that when using this method of iteration.
     #
+    # @param timeout_ms [Integer] Timeout for each poll iteration
     # @yieldparam message [Message] Received message
     # @return [nil]
     # @raise [RdkafkaError] When polling fails
-    def each
+    def each(timeout_ms: Defaults::CONSUMER_POLL_TIMEOUT_MS)
       loop do
-        message = poll(250)
+        message = poll(timeout_ms)
         if message
           yield(message)
         else
@@ -609,7 +612,13 @@ module Rdkafka
       end
     end
 
-    # Deprecated. Please read the error message for more details.
+    # @deprecated This method has been removed due to data consistency concerns
+    # @param max_items [Integer] unused
+    # @param bytes_threshold [Numeric] unused
+    # @param timeout_ms [Integer] unused
+    # @param yield_on_error [Boolean] unused
+    # @param block [Proc] unused block
+    # @raise [NotImplementedError] Always raises as this method is no longer supported
     def each_batch(max_items: 100, bytes_threshold: Float::INFINITY, timeout_ms: 250, yield_on_error: false, &block)
       raise NotImplementedError, <<~ERROR
         `each_batch` has been removed due to data consistency concerns.
@@ -646,6 +655,9 @@ module Rdkafka
 
     private
 
+    # Checks if the consumer is closed and raises an error if so
+    # @param method [Symbol] name of the calling method for error context
+    # @raise [ClosedConsumerError] when the consumer is closed
     def closed_consumer_check(method)
       raise Rdkafka::ClosedConsumerError.new(method) if closed?
     end

data/lib/rdkafka/defaults.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Rdkafka
+  # Default timeout and timing values used throughout rdkafka-ruby.
+  #
+  # All timeout values can be overridden per-call via method parameters.
+  # These constants provide a central place to understand and reference
+  # the default values used across the library.
+  #
+  # @note These are rdkafka-ruby defaults, not librdkafka configuration options.
+  #   For librdkafka options, see:
+  #   https://github.com/confluentinc/librdkafka/blob/master/CONFIGURATION.md
+  #
+  # @example Overriding a timeout per-call
+  #   consumer.committed(timeout_ms: 5_000)  # Use 5 seconds instead of default 2 seconds
+  #
+  # @example Checking the default value
+  #   Rdkafka::Defaults::CONSUMER_COMMITTED_TIMEOUT_MS  # => 2000
+  module Defaults
+    # Consumer timeouts (in milliseconds)
+
+    # Default timeout for fetching committed offsets
+    # @see Consumer#committed
+    CONSUMER_COMMITTED_TIMEOUT_MS = 2_000
+
+    # Default timeout for querying watermark offsets
+    # @see Consumer#query_watermark_offsets
+    CONSUMER_QUERY_WATERMARK_TIMEOUT_MS = 1_000
+
+    # Default timeout for lag calculation watermark queries
+    # @see Consumer#lag
+    CONSUMER_LAG_TIMEOUT_MS = 1_000
+
+    # Default timeout for offsets_for_times operation
+    # @see Consumer#offsets_for_times
+    CONSUMER_OFFSETS_FOR_TIMES_TIMEOUT_MS = 1_000
+
+    # Default poll timeout for Consumer#each iterator
+    # @see Consumer#each
+    CONSUMER_POLL_TIMEOUT_MS = 250
+
+    # Seek operation timeout (0 = non-blocking)
+    # @see Consumer#seek_by
+    CONSUMER_SEEK_TIMEOUT_MS = 0
+
+    # Events poll timeout (0 = non-blocking/async)
+    # @see Consumer#events_poll
+    CONSUMER_EVENTS_POLL_TIMEOUT_MS = 0
+
+    # Producer timeouts (in milliseconds)
+
+    # Default timeout for producer flush operation
+    # @see Producer#flush
+    PRODUCER_FLUSH_TIMEOUT_MS = 5_000
+
+    # Default flush timeout during purge operation
+    # @see Producer#purge
+    PRODUCER_PURGE_FLUSH_TIMEOUT_MS = 100
+
+    # Metadata timeouts (in milliseconds)
+
+    # Default timeout for metadata requests
+    # @see Admin#metadata
+    # @see Metadata#initialize
+    METADATA_TIMEOUT_MS = 2_000
+
+    # Handle wait timeouts (in milliseconds)
+
+    # Default maximum wait timeout for async handles (delivery, admin operations)
+    # @see AbstractHandle#wait
+    HANDLE_WAIT_TIMEOUT_MS = 60_000
+
+    # Native Kafka polling (in milliseconds)
+
+    # Default poll timeout for producer/admin native polling thread
+    # @see Config#producer
+    # @see Config#admin
+    NATIVE_KAFKA_POLL_TIMEOUT_MS = 100
+
+    # Internal timing (in milliseconds)
+
+    # Sleep interval during purge wait loop
+    # @see Producer#purge
+    PRODUCER_PURGE_SLEEP_INTERVAL_MS = 1
+
+    # Sleep interval while waiting for operations to complete in NativeKafka#synchronize
+    # @see NativeKafka#synchronize
+    NATIVE_KAFKA_SYNCHRONIZE_SLEEP_INTERVAL_MS = 10
+
+    # Base backoff factor for metadata retry in milliseconds (multiplied by 2^attempt)
+    # @see Metadata#initialize
+    METADATA_RETRY_BACKOFF_BASE_MS = 100
+
+    # Cache settings (in milliseconds)
+
+    # Default time-to-live for cached partition counts
+    # @see Producer::PartitionsCountCache
+    PARTITIONS_COUNT_CACHE_TTL_MS = 30_000
+
+    # Configuration values (not time-based)
+
+    # Maximum number of metadata fetch retry attempts
+    # @see Metadata#initialize
+    METADATA_MAX_RETRIES = 10
+  end
+end

data/lib/rdkafka/error.rb

@@ -19,6 +19,9 @@ module Rdkafka
     attr_reader :broker_message
 
     # @private
+    # @param response [Integer] the raw error response code from librdkafka
+    # @param message_prefix [String, nil] optional prefix for error messages
+    # @param broker_message [String, nil] optional error message from the broker
     def initialize(response, message_prefix=nil, broker_message: nil)
       raise TypeError.new("Response has to be an integer") unless response.is_a? Integer
       @rdkafka_response = response
@@ -55,6 +58,8 @@ module Rdkafka
     end
 
     # Error comparison
+    # @param another_error [Object] object to compare with
+    # @return [Boolean]
     def ==(another_error)
        another_error.is_a?(self.class) && (self.to_s == another_error.to_s)
     end
@@ -66,6 +71,9 @@ module Rdkafka
     attr_reader :topic_partition_list
 
     # @private
+    # @param response [Integer] the raw error response code from librdkafka
+    # @param topic_partition_list [TopicPartitionList] the topic partition list with error info
+    # @param message_prefix [String, nil] optional prefix for error messages
     def initialize(response, topic_partition_list, message_prefix=nil)
       super(response, message_prefix)
       @topic_partition_list = topic_partition_list
@@ -74,6 +82,7 @@ module Rdkafka
 
   # Error class for public consumer method calls on a closed consumer.
   class ClosedConsumerError < BaseError
+    # @param method [Symbol] the method that was called
     def initialize(method)
       super("Illegal call to #{method.to_s} on a closed consumer")
     end
@@ -81,21 +90,27 @@ module Rdkafka
 
   # Error class for public producer method calls on a closed producer.
   class ClosedProducerError < BaseError
+    # @param method [Symbol] the method that was called
     def initialize(method)
       super("Illegal call to #{method.to_s} on a closed producer")
     end
   end
 
-  # Error class for public consumer method calls on a closed admin.
+  # Error class for public admin method calls on a closed admin.
   class ClosedAdminError < BaseError
+    # @param method [Symbol] the method that was called
     def initialize(method)
       super("Illegal call to #{method.to_s} on a closed admin")
     end
   end
 
+  # Error class for calls on a closed inner librdkafka instance.
   class ClosedInnerError < BaseError
     def initialize
       super("Illegal call to a closed inner librdkafka instance")
     end
   end
+
+  # Error class for librdkafka library loading failures (e.g., glibc compatibility issues).
+  class LibraryLoadError < BaseError; end
 end

data/lib/rdkafka/helpers/oauth.rb

@@ -1,6 +1,6 @@
 module Rdkafka
   module Helpers
-
+    # OAuth helper methods for setting and refreshing SASL/OAUTHBEARER tokens
     module OAuth
 
       # Set the OAuthBearer token
@@ -47,8 +47,11 @@ module Rdkafka
 
       private
 
-      # Convert extensions hash to FFI::MemoryPointer (const char **).
-      # Note: the returned pointers must be freed manually (autorelease = false).
+      # Convert extensions hash to FFI::MemoryPointer (`const char **`).
+      #
+      # @param extensions [Hash, nil] extension key-value pairs
+      # @return [Array<FFI::MemoryPointer, Array<FFI::MemoryPointer>>] array pointer and string pointers
+      # @note The returned pointers must be freed manually (autorelease = false).
       def map_extensions(extensions)
         return [nil, nil] if extensions.nil? || extensions.empty?
 
@@ -74,8 +77,11 @@ module Rdkafka
         [array_ptr, str_ptrs]
       end
 
-      # extension_size is the number of keys + values which should be a non-negative even number
-      # https://github.com/confluentinc/librdkafka/blob/master/src/rdkafka_sasl_oauthbearer.c#L327-L347
+      # Returns the extension size (number of keys + values).
+      #
+      # @param extensions [Hash, nil] extension key-value pairs
+      # @return [Integer] non-negative even number representing keys + values count
+      # @see https://github.com/confluentinc/librdkafka/blob/master/src/rdkafka_sasl_oauthbearer.c#L327-L347
       def extension_size(extensions)
         return 0 unless extensions
         extensions.size * 2

data/lib/rdkafka/metadata.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
 module Rdkafka
+  # Provides cluster metadata information
   class Metadata
-    attr_reader :brokers, :topics
+    # @return [Array<Hash>] list of broker metadata
+    attr_reader :brokers
+    # @return [Array<Hash>] list of topic metadata
+    attr_reader :topics
 
     # Errors upon which we retry the metadata fetch
     RETRIED_ERRORS = %i[
@@ -12,7 +16,13 @@ module Rdkafka
 
     private_constant :RETRIED_ERRORS
 
-    def initialize(native_client, topic_name = nil, timeout_ms = 2_000)
+    # Fetches metadata from the Kafka cluster
+    #
+    # @param native_client [FFI::Pointer] pointer to the native Kafka client
+    # @param topic_name [String, nil] specific topic to fetch metadata for, or nil for all topics
+    # @param timeout_ms [Integer] timeout in milliseconds
+    # @raise [RdkafkaError] when metadata fetch fails
+    def initialize(native_client, topic_name = nil, timeout_ms = Defaults::METADATA_TIMEOUT_MS)
       attempt ||= 0
       attempt += 1
 
@@ -35,12 +45,12 @@ module Rdkafka
       metadata_from_native(ptr.read_pointer)
     rescue ::Rdkafka::RdkafkaError => e
       raise unless RETRIED_ERRORS.include?(e.code)
-      raise if attempt > 10
+      raise if attempt > Defaults::METADATA_MAX_RETRIES
 
       backoff_factor = 2**attempt
-      timeout = backoff_factor * 0.1
+      timeout_ms = backoff_factor * Defaults::METADATA_RETRY_BACKOFF_BASE_MS
 
-      sleep(timeout)
+      sleep(timeout_ms / 1000.0)
 
       retry
     ensure
@@ -50,6 +60,8 @@ module Rdkafka
 
     private
 
+    # Extracts metadata from native pointer
+    # @param ptr [FFI::Pointer] pointer to native metadata
     def metadata_from_native(ptr)
       metadata = Metadata.new(ptr)
       @brokers = Array.new(metadata[:brokers_count]) do |i|
@@ -69,7 +81,11 @@ module Rdkafka
       end
     end
 
+    # Base class for metadata FFI structs with hash conversion
+    # @private
     class CustomFFIStruct < FFI::Struct
+      # Converts struct to a hash
+      # @return [Hash]
       def to_h
         members.each_with_object({}) do |mem, hsh|
           val = self.[](mem)
@@ -80,6 +96,8 @@ module Rdkafka
       end
     end
 
+    # @private
+    # FFI struct for rd_kafka_metadata_t
     class Metadata < CustomFFIStruct
       layout :brokers_count, :int,
              :brokers_metadata, :pointer,
@@ -89,12 +107,16 @@ module Rdkafka
              :broker_name, :string
     end
 
+    # @private
+    # FFI struct for rd_kafka_metadata_broker_t
     class BrokerMetadata < CustomFFIStruct
       layout :broker_id, :int32,
              :broker_name, :string,
              :broker_port, :int
     end
 
+    # @private
+    # FFI struct for rd_kafka_metadata_topic_t
     class TopicMetadata < CustomFFIStruct
       layout :topic_name, :string,
              :partition_count, :int,
@@ -102,6 +124,8 @@ module Rdkafka
              :rd_kafka_resp_err, :int
     end
 
+    # @private
+    # FFI struct for rd_kafka_metadata_partition_t
     class PartitionMetadata < CustomFFIStruct
       layout :partition_id, :int32,
              :rd_kafka_resp_err, :int,

data/lib/rdkafka/native_kafka.rb

@@ -4,7 +4,13 @@ module Rdkafka
   # @private
   # A wrapper around a native kafka that polls and cleanly exits
   class NativeKafka
-    def initialize(inner, run_polling_thread:, opaque:, auto_start: true, timeout_ms: 100)
+    # Creates a new NativeKafka wrapper
+    # @param inner [FFI::Pointer] pointer to the native Kafka handle
+    # @param run_polling_thread [Boolean] whether to run a background polling thread
+    # @param opaque [Rdkafka::Opaque] opaque object for callback context
+    # @param auto_start [Boolean] whether to start the polling thread automatically
+    # @param timeout_ms [Integer] poll timeout in milliseconds
+    def initialize(inner, run_polling_thread:, opaque:, auto_start: true, timeout_ms: Defaults::NATIVE_KAFKA_POLL_TIMEOUT_MS)
       @inner = inner
       @opaque = opaque
       # Lock around external access
@@ -37,6 +43,8 @@ module Rdkafka
       @closing = false
     end
 
+    # Starts the polling thread if configured
+    # @return [nil]
     def start
       synchronize do
         return if @started
@@ -69,6 +77,10 @@ module Rdkafka
       end
     end
 
+    # Executes a block with the inner native Kafka handle
+    # @yield [FFI::Pointer] the inner native Kafka handle
+    # @return [Object] the result of the block
+    # @raise [ClosedInnerError] when the inner handle is nil
     def with_inner
       if @access_mutex.owned?
         @operations_in_progress += 1
@@ -81,26 +93,38 @@ module Rdkafka
       @decrement_mutex.synchronize { @operations_in_progress -= 1 }
     end
 
+    # Executes a block while holding exclusive access to the native Kafka handle
+    # @param block [Proc] block to execute with the native handle
+    # @yield [FFI::Pointer] the inner native Kafka handle
+    # @return [Object] the result of the block
     def synchronize(&block)
       @access_mutex.synchronize do
         # Wait for any commands using the inner to finish
         # This can take a while on blocking operations like polling but is essential not to proceed
         # with certain types of operations like resources destruction as it can cause the process
         # to hang or crash
-        sleep(0.01) until @operations_in_progress.zero?
+        sleep(Defaults::NATIVE_KAFKA_SYNCHRONIZE_SLEEP_INTERVAL_MS / 1000.0) until @operations_in_progress.zero?
 
         with_inner(&block)
       end
     end
 
+    # Returns a finalizer proc for closing this native Kafka handle
+    # @return [Proc] finalizer proc
     def finalizer
       ->(_) { close }
     end
 
+    # Returns whether this native Kafka handle is closed or closing
+    # @return [Boolean] true if closed or closing
     def closed?
       @closing || @inner.nil?
     end
 
+    # Closes the native Kafka handle and cleans up resources
+    # @param object_id [Integer, nil] optional object ID (unused, for finalizer compatibility)
+    # @yield optional block to execute before destroying the handle
+    # @return [nil]
     def close(object_id=nil)
       return if closed?
 

data/lib/rdkafka/producer/delivery_report.rb

@@ -32,8 +32,12 @@ module Rdkafka
       # We do not remove the original `#topic_name` because of backwards compatibility
       alias topic topic_name
 
-      private
-
+      # @private
+      # @param partition [Integer] partition number
+      # @param offset [Integer] message offset
+      # @param topic_name [String, nil] topic name
+      # @param error [Integer, nil] error code if any
+      # @param label [Object, nil] user-defined label
       def initialize(partition, offset, topic_name = nil, error = nil, label = nil)
         @partition = partition
         @offset = offset