Change argument order of poll_read and poll_write

[seanmonstar]

This may just be my personal opinion, but I feel the buf argument is... "more important"? Something... And it that it should come before the Context argument in AsyncRead::{poll_read, poll_vectored_read} and AsyncWrite::{poll_write, poll_vectored_write}.

This just feels more natural to me:

tcp.poll_read(&mut buf, cx)

VS

tcp.poll_read(cx, &mut buf)

As some additional evidence, it seems Fuchsia feels similarly, as their impl AsyncRead and impl AsyncWrite reorder the arguments to the real method.

---

I suspect when building poll-like methods in libraries, I'd opt to put the Context as the last argument, since it's the least important to understand what is being passed to the function.

[carllerche]

I also prefer cx at the end.

[aturon]

This was a deliberate choice based on similar reasoning but with the opposite conclusion: since the convention is to use cx, it's easier to visually skip over it when it has a consistent placement as an early argument, leaving room at the end for longer computations, vs having a distracting trailing cx.

[seanmonstar]

I'm just proposing that the choice may want to be reconsidered, when authors of a bunch of futures stuff have all wanted the order reversed:

• hyper
• tokio
• fuchsia

[seanmonstar]

cc @cramertj

[aturon]

@seanmonstar yes, I understand that, but this decision was made with consultation with @cramertj on Fuchsia, and I don't want to take the time to relitigate it.

[carllerche]

@aturon Totally understandable! Is there a link to the previous discussion so that arguments already made don't have to be repeated?

[seanmonstar]

this decision was made with consultation

Is there a record of where this took place? If it took place solely in the IRC room, it seems like these are sorts of things that should be discussed in an issue instead.

I don't want to take the time to relitigate it.

I, er, wasn't trying to litigate. I just saw something in a library that I care deeply about, and not seeing it mentioned anywhere, wanted to discuss a change.

Is there some other way one should offer thoughts without sounding like I want to go to court?

[carllerche]

I mostly ask for the previous discussion to catch up. I'm going to have to pick argument order as well on fns in Tokio + other libs, so it would be helpful to read the context.

[cramertj]

The discussion logs were as follows:

<aturon> cramertj: "small" thing -- do we have/want a convention about where the `cx` argument goes?
<aturon> looks like here you're leaning toward "last arg"
<cramertj> that was what I was leaning towards, but I don't really care too much
<cramertj> and I don't think I was consistent
<aturon> hm
<aturon> that coudl def be a papercut (consistency)
<cramertj> yup
<aturon> personally i would make it an early arg
<cramertj> sgtm
<cramertj> I can grep around and change them
<aturon> (that allows you to more quickly scan args)
<aturon> cool <3

Which resulted in this comment and the subsequent change. As you can tell, I don't have a super strong opinion about this, nor do I care to develop one ;). I suppose you could imagine it mattering if we had currying / partial function application, but we don't (and even if we did, it's not clear exactly which direction the bias would lead).

[cramertj]

As for the fuchsia changes linked in the original issue, that's just fallout from me making the changes at the same time as I was implementing the futures-io code.

[aturon]

I'm sorry for my impatience here; being involved in a very large number of projects that are constantly involving "reconsideration" is pretty tiring, and I've been trying to drive down the issue count on futures. Sometimes a small issue of personal taste like this should just get a decision and move on, IMO.

That said, it's now costing more time and emotional energy than it would to just have the discussion, so I've reopened.

Personally, I think the argument can be made in either direction for the ordering question, but for me an important aspect is that we should not "reserve" the final argument position that is often used for closures (because having non-final closure arguments gets messy). I also stand by my position that consistently keeping this as the first argument makes it easier to scan past than seeing trailing , cx in arbitrary locations.

[carllerche]

IMO the closure argument as the last arg is pretty solid. Thanks for providing the context.

[aturon]

No problem, and sorry again for the earlier abruptness. I'll close again :-)

[seanmonstar]

I think putting the closure on the end probably is better (I haven't need to try it yet, but sounds good)!

I expect that besides that, however, I'd personally opt for putting the Context on the end, since I actually find needing to skip over , cx, to find the arguments I do need to be more annoying. 🤷‍♂️

Sorry if I came off as combative, I genuinely just wanted to discuss its merits, or get the past discussion in a easily findable place. Thanks!