Make receive backpressure clearer

[mwelzl]

From the review by Robert Wilton:

p 70, sec 9.3.2. Receive Events

  Each call to Receive will be paired with a single Receive event,
  which can be a success or an error.  This allows an application to
  provide backpressure to the transport stack when it is temporarily
  not ready to receive Messages.

The backpressure aspect wasn't entirely clear to me. So, if an application can
handle receiving multiple receive events at the same time, it can make multiple
calls to receive without waiting for, or processing, any receive events? Is
that how the application controls the backpressure?

Also:

How does the transport stack know that the application has finished with the
memory holding the message in the receive event, or is the expectation that the
receive message contents is logically always allocated on the heap and it is
responsibility of the receiver to free the memory once it is done with it?

[mwelzl]

Clearly, the answer to his first question is "yes". I thought the text is clear enough, but we can just add a sentence, turning his question into an example, e.g.:

For example, if an application can handle receiving multiple receive events at the same time, it can make multiple
calls to receive without waiting for, or processing, any receive events.

About the second question, I think that, as in #1282, there are multiple ways to implement this concretely, and such memory management questions are beyond the scope of our abstract API. What do others think?

[gorryfair]

I think an example is good,( but the design is an implementation / style. The proposed wording still needs a little crafting: "For example, an application that receives multiple receive events can process..."

[gorryfair]

Is /which can be a success or an error/which can return a success or an error/?

[mwelzl]

Maybe not: the event returns data, and it can, hm, contain an error? Also convey an error? Be an error event?

Seriously, let's just remove: "which can be a success or an error." - it's really not needed.