What is the point of the timeout in i2c_master_cmd_begin()?

[RobMeades]

Hi: I'm just beginning to use the I2C functions on an ESP32 device. I see that the I2C API is not thread-safe, which is fine, I can handle thread safety in my application. But I also see that i2c_master_cmd_begin() includes a time-out value. My question is: why is a timeout value needed if I am required, in any case, to handle thread-safety in my application?

The implication is that the I2C functions can return before the HW has completed it's work, something I would not be able to handle at application level, but I don't see how that's possible as it can only return once all of the traffic on the interface is handled correctly (NACK/ACK) in order to return the success or failure of the I2C transaction, the HW must necessarily complete it's job before the API function can return.

Can anyone explain what the timeout on i2c_master_cmd_begin() is actually doing? Without some information it's rather difficult to decide what value the timeout should be set to.