What is a push?

[sunfishcode]

#4 introduces the concept of read returning a status, which can be ready, end, or push. The first two are fairly obvious, but push is a new concept, and is not fully defined yet.

It is similar in intent to the TCP PUSH flag. It means: go ahead and process the data that's been received so far, before trying to read more data. This avoids situations where data in a long pipeline gets stuck in the middle where something is waiting for more data to fill up a buffer before sending it through.

In theory we could return push when a TCP push is received, except the host OS APIs we'll implement this with don't expose the PUSH flag in a way that supports this:

• On the sending side PUSH is implicitly set after each send and there is no flush function, so there's no way to tell the difference between a send which needs to be pushed and one which will be immediately followed by more data anyway.
• On the receiving side, PUSH is not reported explicitly, and there's no way to tell the difference between a read which ended in a PUSH and one which ended for other reasons.

A push is not meant to be semantically relevant. Programs generally shouldn't behave differently if their input comes from a user typing in text on a line-oriented terminal, which might send pushes at each newline, or reading from a file, which might not.

A particular open question is, how do pushes interact with errors? #4 proposes that read defer errors so that when an error is returned, there's nothing left for user code to do and it can just fail immediately. To make sure user code doesn't worry about pending buffered data, it specifies a push once the remaining data is read, before reporting the error. However, it's not yet clear whether this is a good design.

[technosophos]

My fundamental feeling at this point is that I am also unsure whether this is the best design abstraction... but I don't have a good reason not to try it. I think it is worth pushing this concept forward and seeing if it holds up. @radu-matei and I have talked through some of the implications, and I think we agree that this line of design is worth pursuing.

[sunfishcode]

There's been a lot of offline discussion about this, which has helped shape the stream type in the component model. I'll attempt to summarize it here:

One of the main motivations for the push concept was to avoid situations where data gets stuck in a buffer in the middle of a pipeline. If the data is urgent, or if the pipeline is being used interactively, we don't want a component in the middle with a larger buffer than its neighbors to wait for its upstream to fill its buffer before sending data to its downstream.

The new idea is that when the middle component with the large buffer does a read, and it gets back less data than requested, the component should attempt to process as much as it can and send what data it can to its downstream, before attempting to read more data.

We can then think about this as a scheduling concern. If the host knows the pipeline is being used interactively, and there's insufficient data for a given request, it can present the component with a short read, and the component will attempt to process it and send it on. If it's not being used interactively, the host may chose to keep the component suspended and schedule the component producing the incoming data multiple times. Instead of having the component itself have logic for retrying a read until the buffer is full, the host's scheduler can effectively do this. Then, the component can be woken up when it has a full buffer, which presumably lets it achieve better throughput.

And in situations where it's desirable for a producer to signal a push, it might be the case that the API is better represented as a stream<list<u8>, _> or so on, or it might be the case that there's a need for an API that lets producers explicitly request things of the host.

With this understanding, the component model stream type does not need a "push" concept.