Understanding espconn_recv_hold

[kolban]

I am reading the 1.4 SDK programming guide and am trying to understand the API called "espconn_recv_hold".

Would it be possible to get a better explanation of what this API means and how it should be used?

My guesses are as follows:

Consider an ESP8266 that is receiving data over the network. Assume that it is receiving 10K/second but yet can only process 5K/second. Obviously the data is arriving faster than can be processed in real time. Since the way the ESP8266 SDK is designed is to invoke the receive callback when the data arrives, what this API does is suspend the invocation of the receive callback. So where then does the data go? My belief is that it is then buffered (throttled) at the transmitter implementing a flow control mechanism. However, I am not 100% convinced this is correct ... does anyone know?

Reading the docs, they say an interesting thing:

"The function does not act immediately; we recommend calling it while reserving 5*1460 bytes of memory."

What does that mean? What does "not act immediately" mean? Where should we be reserving 7300 bytes of memory and what is its purpose?

I have a guess that when we call "espconn_recv_hold" that there may already be in-flight data that has already been acknowledged that may be up to 7300 bytes in length ... is that correct?

Hoping we can all have a forum chat on this interesting function.