Re: [whatwg/streams] Note about underlyingSink close() method is misleading (#617)

I think what @tyoshino said makes sense, but an API where `writer.close()` called `underlyingSink.abort()` would make people think we were insane.

I had another idea, which is to replace `close()` and `abort()` on `underlingSink` with `shutdown()` and `destroy(why, e)`. The key difference is that `destroy()` would _always_ be called if it was defined.

`writer.close()` would wait for all queued writes to complete, then call `underlyingSink.shutdown()`, then `underlyingSink.destroy('close', undefined)`.
`writer.abort(e)` would call `underlyingSink.destroy('abort', e)`.
`writer.close(); writer.abort(e);` would call `underlingSink.shutdown()` and `underlyingSink.destroy('abort', e);`, possibly concurrently, if there were no queued writes.

`shutdown()` is named by analogy with BSD sockets **shutdown**(2), ie. it cleanly terminates the connection without freeing local resources. It would typically be used for flushing buffers.
`destroy(why, e)` is named like the common pattern in garbage-collected or reference-counted systems when some resources need to be explicitly freed. This would often map to a `close()` call internally. In systems where there are two exclusive ways to free the resource, for example `commit()` and `rollback()`, this would have to switch on `why`.

This would be a big API change and I am not sure of the benefits.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/streams/issues/617#issuecomment-262220474