Document Producer.flush default timeout

[cdeil]

Looking at the Producer.flush and Producer.poll docs it's not clear if the timeout parameter is required or optional.

Probably it's optional and there is a default of -1 for infinite timeout, as in Producer.list_topics?

Could you please clarify in the docstring?

[rnpridgeon]

Thanks, I'll get this updated. You may or may not find the following notes useful, they are mostly being added as a reference for myself for when I come back to this.

librdkafka definitions

There are two magic numbers used by rdkafka's timespec; their names accurately describe their intent.

https://github.com/edenhill/librdkafka/blob/master/src/rdtime.h#L60-L61

#define RD_POLL_INFINITE  -1
#define RD_POLL_NOWAIT     0

A condition variable is used to block the thread until an op is served or the timeout elapses.

https://github.com/edenhill/librdkafka/blob/master/src/rdkafka_queue.c#L462

https://github.com/edenhill/librdkafka/blob/master/src/tinycthread_extra.c#L97-L104

Python binding timeout default behavior:

Poll default behavior:

Producer_poll requires a timeout param providing no default.

https://github.com/confluentinc/confluent-kafka-python/blob/master/confluent_kafka/src/Producer.c#L363

Admin_poll requires a timeout param providing no default.

https://github.com/confluentinc/confluent-kafka-python/blob/master/confluent_kafka/src/Admin.c#L1008

Consumer_poll does not require a timeout param. This defaults to RD_POLL_INFINITE

https://github.com/confluentinc/confluent-kafka-python/blob/master/confluent_kafka/src/Consumer.c#L882

https://github.com/confluentinc/confluent-kafka-python/blob/master/confluent_kafka/src/Consumer.c#L870

flush default behavior:

Producer_flush does not require a timeout param; Defaults to RD_POLL_INFINITE

https://github.com/confluentinc/confluent-kafka-python/blob/master/confluent_kafka/src/Producer.c#L383

https://github.com/confluentinc/confluent-kafka-python/blob/master/confluent_kafka/src/Producer.c#L376

list_topics default behavior:

list_topics(Producer and Admin) does not require a timeout param; Defaults to RD_POLL_INFINITE

https://github.com/confluentinc/confluent-kafka-python/blob/master/confluent_kafka/src/Metadata.c#L349

https://github.com/confluentinc/confluent-kafka-python/blob/master/confluent_kafka/src/Metadata.c#L346

[cdeil]

@rnpridgeon - Thank you!
Having the defaults for those visible in the docs will be really useful.

[deeTEEcee]

It would be nice to be able to set a default somewhere or enforce it as a required field. I hit the timeout issue so often in the application